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SUMMARY OF TECHNICAL CHANGES 



This revision of the Executive Reference Manual contains changes and 
additions to document two operating systems: RSX-llM V3.2 and 
RSX~11M-PLUS VI. 0. 



TECHNICAL CHANGES COMMON TO RSX-llM AND RSX-llM-PLUS SYSTEMS 

The following list contains a brief summary of technical changes for 
both operating systems (RSX-llM/M-PLUS) : 

1. Parent/offspring tasking support has been added, including 
the following new directives: 

Spawn 

Connect 

Exit With Status 

2. Stop-bit synchronization of tasks is now supported using the 
following- new directives: 

Stop 

Receive Data Or Stop 

Stop For Logical 'OR' Of Event Flags 

Stop For Single Event Flag 

Unstop 

3. Group global event flags have been added, including a new 
data structure containing 32 event flags and the following 
directives: 

Create Group Global Event Flags 
Eliminate Group Global Event Flags 
Read Extended Event Flags 

4. Task images built on RSX-llM V3.1 and V3.2 will run in 
compatibility mode under VAX/VMS VI. 0, VI. 01, and VI. 5 with 
certain restrictions. The restrictions, including those 
involving RSX-llM Executive services described in this 
manual, are described in detail in the VAX-11/RSX-llM 
Programm er's Reference Manua l . 

With the next major release of VAX/VMS, some of the 

restrictions currently imposed for RSX-llM tasks are expected 

to change. Therefore, refer to the current VAX/VMS 
documentation for the specific system in use. 
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TECHNICAL CHANGES FOR RSX-llM-PLUS SYSTEMS 

Executive support added for RSX-llM-PLUS operating systems is 
described in Chapter 5. The following list is a brief summary of 
technical changes for this support: 

1. In addition to the parent/offspring tasking support 
previously listed for both operating systems, the following 
new directives are added: 

Send, Request And Connect 
Emit Status 

2. Virtual terminal support is added, allowing parent, tasks to 
execute terminal I/O with offspring tasks via terminals 
implemented in software. New directives added for virtual 
terminal support include: 

Create Virtual Terminal 
Eliminate virtual Terminal 

3. New CPU/UNIBUS affinity support directives have been added, 
allowing task selection of CPU (in multiprocessor system 
environments) and UNIBUS run, as follows; 

Set Affinity 
Remove Affinity 

4. A Supervisor mode library support directive has been added, 
allowing user tasks to map Supervisor I-space (in addition to 
User D-space) , as follows: 

Supervisor Call 

5. Variable-length send/receive data buffers are now supported 
via the following new directives: 

Variable Receive Data 

Variable Receive Data Or Stop 

Variable Receive Data Or Exit 

Variable Send Data 

6. Support of the exit Asynchronous System Trap (AST) routine 
for tasks that abort via directive or MCR is provided by the 
following new directive: 

Specify Requested Exit AST 

7. Support of the parity error AST routine is now provided for 
diagnostic purposes via the following new directive: 

Specify Parity Error AST 
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PREFACE 



MANUAL OBJECTIVES 

The RSX-llM/M-PLUS Executive Reference Manual describes the system 
directives that allow experienced MACRO-11 and FORTRAN programmers to 
use Executive services to control the execution and interaction of 
tasks. 



INTENDED AUDIENCE 

The intended audience for this manual are software developers who are 
experienced users of MACRO-11 or FORTRAN for user task generation. 
Information contained in this manual is intended for reference only; 
no attempt is made to describe the procedures involved in developing 
user tasks beyond the detailed reference information normally required 
for directive use. However, Chapters 1 through 5 do contain much 
information that will aid in better understanding how directives can 
be effectively used in the RSX-llM/M-PLUS multitasking environment. 
Convenient quick-reference material is included in appendixes at the 
end of the manual for use by the more advanced RSX-llM/M-PLUS 
programmer . 



STRUCTURE OF THIS DOCUMENT 

A Summary Of Technical Changes provides the experienced RSX-llM user 
with a quick summary of changes to system software since the previous 
version of this manual. Comments are general and serve only as a 
guide to areas of change. 

Chapter 1 defines system directives and describes their use in both 
MACRO-11 and FORTRAN programs. 

Chapter 2 defines significant events, event flags, system traps, and 
stop-bit synchronization and describes their relationship to system 
directives. 

Chapter 3 introduces the concept of extended logical address space 
within the framework of memory management directives. 

Chapter 4 introduces the concept of parent/offspring tasking, 
including associated directives, generated data structures, and task 
communications. 

Chapter 5 introduces the additional Executive support provided in 
RSX-llM-PLUS. This includes system directives for Supervisor mode 
library support, additional parent/offspring tasking and task 
communications support, task CPU and UNIBUS affinity support, virtual 
terminal support for offspring tasks, and additional AST routine 
support . 
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Chapter 6 contains a short summary of all directives, arranged 

according to their functional categories. The summary is followed by 

detailed descriptions of each system directive arranged alphabetically 0^ 

according to macro call. r 

Appendix A contains directives arranged alphabetically according to 
macro call. Abbreviated specifications include directive name, 
FORTRAN call, macro call, and parameters only. 

Appendix B lists the standard error codes returned by the RSX-llM or * 

RSX-llM-PLUS Executive. 

Appendix C lists Directive Identification Codes for all directives in 
the exact octal values as they appear in the Directive Parameter 
Block. A description of how the values are obtained is included. » 

Appendix D lists all directives, the operating systems where the 

individual directives are available (RSX-llS, RSX-llM, or 

RSX-llM-PLUS), and the SYSGEN option required (if applicable) to 
obtain that directive support. 



ASSOCIATED DOCUMENTS 

Manuals that are prerequisite sources of information for readers of 
this manual are: RSX-llM/M-PLUS Task Builder Manual and either 
IAS/RSX-11 MACRO-11 Reference Manual , or IAS/RSX-11 FORTRAN IV User's 
Guide , or FORTRAN IV-PLUS User's Guide . 

Other documents related to the contents of this manual are described 
briefly in the appropriate Documentation Directory supplied with the 
software kit. 



CONVENTIONS USED IN THIS DOCUMENT 

Whenever necessary, information that is applicable to a specific 
operating system (RSX-llM or RSX-llM-PLUS) is clearly indicated. In 
addition, for ease of reference, those portions of text that apply to 
RSX-llM-PLUS only are indicated by 'backgroiihiJ 'shading on the printed 
page. 



CHAPTER 1 
USING SYSTEM DIRECTIVES 



This chapter describes the use of system directives and the ways in 
which they are processed. Some of the Executive services described in 
this manual are optional RSX-llS, RSX-llM, or RSX-llM-PLUS features 
and may not be present in the system you are currently using. The 
discussion of the system directives assumes that all possible features 
are present in your system. See the appropriate system generation 
manual for a list of optional features. 



1.1 INTRODUCTION 

When a task requests the Executive to perform an indicated operation, 
this process is called a system directive. The programmer uses the 
directives to control the execution and interaction of tasks. The 
MACRO-11 programmer usually issues directives in the form of macros 
defined in the system macro library. The FORTRAN programmer issues 
system directives in the form of calls to subroutines contained in the 
system object module library. 

System directives enable tasks to: 

• Obtain task and system information 

• Measure time intervals 

• Perform I/O functions 

• Communicate with other tasks 

• Manipulate a task's logical and virtual address space 

• Suspend and resume execution 

• Exit 

Directives are implemented via the EMT 377 instruction. EMT through 
EMT 376 (or 375 for unmapped tasks and mapped privileged tasks) are 
considered to be non-RSX EMT synchronous system traps. They cause the 
Executive to abort the task unless the task has specified that it 
wants to receive control when such traps occur. Note that RSX-llM 
reserves EMT 370 and above for use as special system traps in case of 
future expansion of system capabilities. 

A MACRO-11 programmer should use the system directives supplied in the 
system macro library for directive calls, rather than hand-coding 
calls to directives. The programmer then need only reassemble the 
program to incorporate any changes in the directive specifications. 
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Sections 1.2, 1.3, and 1.6 are directed to all users. Section 1.4 
specifically describes the use of macros, while Section 1.5 describes 
the use of FORTRAN subroutine calls. Programmers using other 
supported languages should refer to the appropriate language reference 
manual supplied by DIGITAL. 



1.2 DIRECTIVE PROCESSING 

Processing a system directive involves four steps: 

1. The user task issues a directive with arguments that are only 
used by the Executive. The directive code and parameters 
that the task, supplies to the system are known as the 
Directive Parameter Block (DPB) . The DPB can be either on 
the user task's stack or in a user task's data section. 

2. The Executive receives an EMT 377 generated by the directive 
macro (or a DIR$ macro) . 

3. The Executive processes the directive. 

4. The Executive returns directive status information to the 
task's Directive Status Word (DSW) . 

Note that the Executive preserves all task registers when a task 
issues a directive. 

The user task issues an EMT 377 (generated by the directive) together 
with the address of a DPB, or a DPB itself, on the top of the issuing 
task's stack. When the stack contains a DPB address, the Executive 
removes the address after processing the directive, and the DPB itself 
remains unchanged. When the stack contains the actual DPB, rather 
than a DPB address, the Executive removes the DPB from the stack after 
processing the directive. 

The first word of each DPB contains a Directive Identification Code 
(DIG) byte, and a DPB size byte. The DIG indicates which directive is 
to be performed; the size byte indicates the DPB length in words. 
The DIG is in the low-order byte of the word, and the size is in the 
high-order byte. 

The DIG is always odd. This allows the Executive to determine whether 
the word on the top of the stack (before EMT 377 was issued) was the 
address of the DPB (even-numbered value) or the first word of the DPB 
(odd-numbered value) . 

The Executive normally returns control to the instruction following 
the EMT. Exceptions to this are directives that result in an exit 
from the task that issued them and Asjynchronous System Trap (AST) 
exit. The Executive also clears or sets the Garry bit in the 
Processor Status word (PS) to indicate acceptance or rejection, 
respectively, of the directive. The DSW, addressed symbolically as 
$DSW-'-, is set to indicate a more specific cause for acceptance or 
rejection of the directive. The DSW usually has a value of +1 for 
acceptance and a range of negative values for rejection (exceptions 
are success return codes for the directives CLEF$, SETF$, and GPRT$, 



1 The Task Builder resolves the address of $DSW. Users addressing 
the DSW with a physical address are not guaranteed compatibility with 
IAS and may experience incompatibilities with future RSX-llM releases. 
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among others). RSX-llM/M-PLUS associate DSW values with symbols, 
using mnemonics that report either successful completion or the cause 
of an error (see Section 1.3). (The ISA FORTRAN calls CALL START and 
CALL WAIT are exceptions; ISA requires positive numeric error codes. 
See Sections 6.3.49 and 6.3.38 for details, the detailed return values 
are listed there with each directive.) 

In the case of successful Exit directives, the Executive does not, of 
course, return control to the task. If an Exit directive fails, 
however, control is returned to the task with an error status in the 
DSW. 

On Exit, the Executive frees task resources as follows: 

1. Detaches all attached devices 

2. Flushes the AST queue (ASTs are described in Chapter 2 of 
this manual . ) 

3. Flushes the clock queues for outstanding Mark Time requests 
for the task (see Section 6.3.38) 

4. Flushes the receive-data and receive-by-ref erence queues 

5. Closes all open files (Files open for write access may be 
left locked.) 

6. Cancels all outstanding I/O 

7. Detaches all attached regions, except in the case of a fixed 
task in a system that supports the memory management 
directives, where no detaching takes place (see Section 
3.3.2) 

8. Frees the task's memory if the task is not fixed 

9. Marks all virtual terminal jnits the task has created for 
Jea..locdtion {see ^.e-'tion 5.2) 



10. Transmits exit status to and disconnects from all connected 
tasks 

If the Executive rejects a directive, it usually does not clear or set 

any specified event flag. Thus, the task may wait indefinitely if it 

indiscriminately executes a Wait For directive corresponding to a 

previously issued Mark Time directive that the Executive has rejected. 
Care should always be taken to ensure that a directive has been 
completed successfully. 



1 . 3 ERROR RETURNS 

As stated above, RSX-llM/M-PLUS associate the error codes with 
mnemonics that report the cause of the error. In the text of the 
manual, the mnemonics are used exclusively. The macro DRERR$, which 
is expanded in Appendix B, provides a correspondence between each 
mnemonic and its numeric value. 

Appendix B also gives the meaning of each error code. In addition, 
each directive description in Chapter 6 contains specific, 
directive-related interpretations of the error codes. 
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1.4 USING THE DIRECTIVE MACROS 



Before issuing 
to create the 
reentrant code 
created on the 
the $S form of 
created in a 
1.4.1.2, which 



a directive, the Macro-11 programmer has to decide how 
DPB. The method depends on whether it is a question of 
or non-reentrant code. With reentrant code, the DPB is 
stack at run time (see Section 1.4.1.3, which describes 
directive) . With non-reentrant code, the DPB is 
data section at assembly time (see Sections 1.4.1.1 and 
describe the $ form and $C form respectively) . 



Figures 1-1 and 1-2 illustrate the alternative directives and 
show the relationship between the stack pointer and the DPB. 



also 



MOV 

EMT 



^ADDR.-ISP) 
377 



SP- 



ADDRESS OF DPB 



DPB 
ITEMS 



SIZE 



Die 



DPB 



jjff^^^ftk 



INCREASING 

MEMORY 

ADDRESSES 



STACK 
GROWTH 



Figure 1-1 Directive Parameter Block (DPB) Pointer on the Stack 



1-4 



USING SYSTEM DIRECTIVES 



MOV 


XX,-(SP) 




PUSH REQUIRED 




DPB ITEMS ON THE 




STACK IN 




REVERSE ORDER 


MOV 


(PC)+,-(SP) 


.BYTE DIC,SIZE 


EMT 


377 



SP 



DPB 
ITEMS 



SIZE 



Die 



STACK 
GROWTH 



INCREASING 

MEMORY 

ADDRESSES 



Figure 1-2 Directive Parameter Block (DPB) on the Stack 



1.4.1 Macro Name Conventions 

To use system directives, a MACRO-11 programmer includes directive 
macro calls in programs. The macros for the RSX-llM directives are 
contained in the System Macro Library (LB: [1,1]RSXMAC.SML) . To make 
the macros available to a program, the programmer issues the .MCALL 
assembler directive. The .MCALL arguments are the names of all the 
macros used in the program. For example: 



CALLING DIRECTIVES FROM THE SYSTEM MACRO LIBRARY 
AND ISSUING THEM. 



,MCALL MRKT$S,WTSE$S 



Additional .MCALLs or code 



MRKT$S 
WTSE$S 



#1,#1,#2,,ERR 
#1 



;MARK TIME FOR 1 SECOND 

;WAIT FOR MARK TIME TO COMPLETE 



Macro names consist of up to four letters, followed by a dollar sign 
($) and, optionally, a C or an S. The optional letter or its absence 
specifies v\^hich of three possible macro expansions the programmer 
wants to use. 
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1.4.1.1 $ Form - The $ form is useful for a directive operation that 
is to be issued several times from different locations in a 
non-reentrant program segment. This form produces only the 
directive's DPB, and must be issued from a data section of the 
program. The code for actually executing a directive that is in the $ 
form is produced by a special macro, DIR$ (discussed in Section 
1.4.2) . 

Because execution of the directive is separate from the creation of 
the directive's DPB: 

1. A $ form of a given directive needs to be issued only once 
(to produce its DPB) . 

2. A DIR$ macro associated with a given directive can be issued 
several times without incurring the cost of generating a DPB 
each time it is issued. 

3. It is easy to access and change the directive's parameters by 
labeling the start of the DPB and using the offsets defined 
by the directive. 

When a program issues the $ form of macro call, the parameters 
required for DPB construction must be valid expressions for MACRO-11 
data storage instructions (such as .BYTE, .WORD, and .RAD50). The 
programmer can alter individual parameters in the DPB. This might be 
done, for example, if the directive is to be used many times with 
varying parameters. 



1.4.1.2 $C Form - Programmers should use the $C form when a directive 

is to be issued only once, and the program segment does not need to be jP^ 

reentrant. The $C form eliminates the need to push the DPB (created 

at assembly time) onto the stack at run time. Other parts of the 

program, however, cannot access the DPB because the DPB address is 

unknown. (Note, in the $C form macro expansion of Section 1.4.5, that 

the DPB address $$$ is redefined by the new value of the assembler's 

location counter each time an additional $C directive is issued.) 

The $C form generates a DPB in a separate p-sectionl called $DPB$$. 

The DPB is first followed by a return to the user-specified p-section, 

then by an instruction to push the DPB address onto the stack, and 

finally by an EMT 377. To ensure that the program reenters the ^^1^^ 

correct p-section, the user must specify the p-section name in the 

argument list immediately following the DPB parameters. If the 

argument is not specified, the program reenters the blank (unnamed) 

p-section. 

This form also accepts an optional final argument that specifies the 
address of a routine to be called (by a JSR instruction) if an error 
occurs during the execution of the directive (see Section 1.4.2). , 

When a program issues the $C form of a macro call, the parameters 
required for DPB construction must be valid expressions for MACRO-11 
data storage instructions (such as .BYTE, .WORD, and .RAD50). (This 
is not true for the p-section argument or the error routine argument, 
which are not part of the DPB.) 



-'- Refer to the lAS/RSX-11 MACRO-11 Programmer's Reference Manual for 
a description of p-sections (program sections). 
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1.4.1.3 $S Form - Program segments that need to be reentrant should 
use the $S form. Only the $S form produces the DPB at run time. The 
other two forms produce the DPB at assembly time. 

In this form, the macro produces code to push a DPB onto the stack, 
followed by an EMT 377. In this case, the parameters must be valid 
source operands for MOV-type instructions. For a 2-word Radix-50 name 
parameter, the argument must be the address of a 2-word block of 
memory containing the name. Note that the Stack Pointer (or any 
reference to the Stack Pointer) should not be used to address 
directive parameters when the $S form is used.l (In the example in 
Section 1.4.1, the error routine argument ERR is a target address for 
a JSR instruction; see Section 1.4.3.) 



1.4.2 DIR$ Macro 

The DIR$ macro allows the programmer to execute a directive with a DPB 
predefined by the $ form of a directive macro. This macro pushes the 
DPB address onto the stack and issues an EMT 377 instruction. 

The DIR$ macro generates an RSX-llM Executive trap using a predefined 
DPB: 

Macro Call: DIR$ adr,err 

adr and err are optional 

adr is the address of the DPB. (The address, if specified, 
must be a valid source address for a MOV instruction.) If 
this address is not specified, the DPB or its address 
must be on the stack. 

err is the address of the error return (see Section 1.4.3). 
If this error return is not specified, an error simply 
sets the carry bit in the Processor Status word. 

NOTE 

DIR$ is not a $ form macro, and does not 
behave as one. There are no variations 
in the spelling of this macro. 



1.4.3 Optional Error Routine Address 

The $C and $S forms of macro calls and the DIR$ macro can accept an 
optional final argument; note that the DIR$ macro is not an Executive 
Directive (DIR$C and DIR$S are not valid macro calls) . The argument 
must be a valid assembler destination operand that specifies the 
address of a user error routine. For example, the DIR$ macro 

DIR$ #DPB, ERROR 



1 Subroutine or macro calls can use the stack for temporary storage, 
thereby destroying the positional relationship between SP and the 
parameters. 
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generates the following code: 



MOV 


#DPB,-(SP) 


EMT 


377 


BCC 


.+6 


JSR 


PC, ERROR 



Since the $ form of a directive macro does not generate any executable 
code, it does not accept an error address argument. 



1.4.4 Symbolic Offsets 

Most system directive macro calls generate local symbolic offsets 
describing the format of the DPB. The symbols are unique to each 
directive, and each is assigned an index value corresponding to the 
number of bytes offset into the DPS that a given DPB element is 
located . 

Because the offsets are defined symbolically, the programmer who must 
refer to or modify DPB elements can do so without knowing the offset 
values. Symbolic offsets also eliminate the need to rewrite programs 
if a future release of RSX-llM changes a DPB specification. 

All $ and $C forms of macros that generate DBPs longer than one w<?rd 
generate local offsets. All informational directives (see Section 
6.1.3), including the $S form, generate local symbolic offsets for the 
parameter block returned as well. 

If the program uses either the $ or $C form and has defined the symbol 
$$$GLB (for example $$$GLB=0) , the macro generates the symbolic 
offsets as global symbols and does not generate the DPB itself. The 
purpose of this facility is to enable the use of a DPB defined in a 
different module. The symbol $$$GLB has no effect on the expansion of 
$S macros. 

When symbolic offsets are used, the use of the $ form of directives is 
recommended . 



^^WBi, 



1.4.5 Examples of Macro Calls 

The examples below show the expansions of the different macro call 

forms. 

1. The $ form generates a DPB only, in the current p-section. 
MRKT$ 1,5,2,MTRAP 
generates the following code: 

"MARK-TIME" DIC & DPB SIZE 
EVENT FLAG NUMBER 
TIME INTERVAL MAGNITUDE 
TIME INTERVAL UNIT (SECONDS) 
AST ENTRY POINT 



.BYTE 


23. ,5 


.WORD 


1 


.WORD 


5 


.WORD 


2 


.WORD 


MTRAP 



The $C form generates in p-section $DPB$$ a DPB, and in 
specified section, the code to issue the directive. 

MRKT$C 1,5,2,MTRAP,PR0G1,ERR 



the 
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generates the following code! 



.PSECT 


$DPB$$ 


$$$=. 




.BYTE 


23. ,5 


.WORD 


1 


.WORD 


5 


.WORD 


2 


.WORD 


MTRAP 


.PSECT 


PROGl 


MOV 


#$$$,-{SP) 


EMT 


377 


BCC 


.+6 


JSR 


PC, ERR 



DEFINE TEMPORARY SYMBOL 

"MARK-TIME" DIG & DPB SIZE 

EVENT FLAG NUMBER 

TIME INTERVAL MAGNITUDE 

TIME INTERVAL UNIT (SECONDS) 

AST ENTRY POINT ADDRESS 

RETURN TO THE ORIGINAL PSECT 

PUSH DPB ADDRESS ON STACK 

TRAP TO THE EXECUTIVE 

BRANCH ON DIRECTIVE ACCEPTANCE 

ELSE, CALL ERROR SERVICE ROUTINE 

The $S form generates code to push the DPB onto the stack and 
to issue the directive. 

MRKT$S #1,#5,#2,R2,ERR 

generates the following code: 

PUSH AST ENTRY POINT 

TIME INTERVAL UNIT (SECONDS) 

TIME INTERVAL MAGNITUDE 

EVENT FLAG NUMBER 

AND "MARK-TIME" DIC & DPB SIZE 

ON THE STACK 

TRAP TO THE EXECUTIVE 

BRANCH ON DIRECTIVE ACCEPTANCE 

ELSE, CALL ERROR SERVICE ROUTINE 

The DIR$ macro issues a directive that has a predefined DPB. 

DIR$ R1,(R3) ; DPB ALREADY DEFINED. DPB ADDRESS IN Rl, 

generates the following code: 



MOV 


R2,-(SP) 


MOV 


#2,-(SP) 


MOV 


#5,-(SP) 


MOV 


#1,-(SP) 


MOV 


(PC)+,-(SP) 


• BYTE 


23. ,5 


EMT 


377 


BCC 


.+6 


JSR 


PC, ERR 



MOV 


R1,-(SP) 


EMT 


377 


BCC 


.+4 


JSR 


PC,(R3) 



PUSH DPB ADDRESS ON STACK 

TRAP TO THE EXECUTIVE 

BRANCH ON DIRECTIVE ACCEPTANCE 

ELSE, CALL ERROR SERVICE ROUTINE 



1.5 FORTRAN SUBROUTINES 

RSX-llM/M-PLUS provide an extensive set of FORTRAN subroutines to 
perform system directive operations. 

The directive descriptions in Chapter 6 describe the FORTRAN 
subroutine calls, as well as the macro calls. 

The FORTRAN Subroutines fall into three basic groups: 

1. Subroutines based on the Instrument Standard of America (ISA) 
Standard ISA 62.1 — These subroutines are included In the 
subroutine descriptions associated with the macro calls (see 
Chapter 6) . 

2. Subroutines designed to use and control specific process 
control interface devices supplied by DIGITAL and supported 
by the RSX-llM/M-PLUS operating systems. 
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3. Subroutines for performing RSX-llM/M-PLUS system directive 
operations — In general, one subroutine is available for 
each directive. (Exceptions are the Mark Time and Run 
directives. The description of Mark Time includes both CALL 
MARK and CALL WAIT. The description of Run includes both 
CALL RUN and CALL START.) 

All the subroutines described in this manual can be called by FORTRAN 
programs compiled by either the FORTRAN IV or FORTRAN IV-PLUS 
compiler . 

These subroutines can also be called from programs written in the 
MACRO-11 assembly language by using PDP-11 FORTRAN calling sequence 
conventions. These conventions are described in the IAS/RSX-11 
FORTRAN IV User's Guide and in the FORTRAN IV-PLUS User's Guide. 



1.5.1 Subroutine Usage 

All the subroutines described in this manual are added to the RSX-llM 
system object module library when either FORTRAN compiler is generated 
for RSX-llM. To use one of these subroutines, the programmer includes 
the appropriate CALL statement in the FORTRAN program. When the 
program is linked to form a task, the Task Builder first checks to see 
whether each specified subroutine is user-defined. If a subroutine is 
not user-defined, the Task Builder automatically searches for it in 
the system object module library. If the subroutine is found, it is 
included in the linked task. 



1.5.1.1 Optional Arguments - Many of the subroutines described in 
this manual have optional arguments. In the subroutine descriptions 
associated with the directives, optional arguments are designated as 
such by being enclosed in square brackets ([]). An argument of this 
kind can be omitted if the comma that immediately follows it is 
retained. If the argument (or string of optional arguments) is last, 
it can simply be omitted, and no comma need end the argument list. 
For example, the format of a call to SUB could be the following; 

CALL SUB (AA, [BB] , [CC] ,DD[, [EE] [,FF] ] ) 

In that event, programmers may omit the arguments BB, CC, EE, and FF 
in one of the following ways: 

• CALL SUB (AA,,,DD,,) 

• CALL SUB (AA, , ,DD) 

In some cases, a subroutine will use a default value for an 
unspecified optional argument. Such default values are noted in each 
subroutine description in Chapter 6. 



1.5.1.2 Task Names - In FORTRAN subroutines, task names may be up to 
six characters long. Characters permitted in a task name are the 
letters A through Z, the numerals through 9 and, the special 
characters dollar sign ($) and period (.). Task names are stored as 
Radix-50 code, which permits up to three characters from the set above 
to be encoded in one PDP-11 word. (Radix-50 is described in detail in 
the IAS/RSX-11 FORTRAN IV User's Guide and the F ORTRAN IV-PLUS User's 
Guide.) 
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FORTRAN subroutine calls require that a task name be defined as a 
variable of type REAL that represents the task name as Radix-50 code. 
This variable may be defined at program compilation time by a DATA 
statement, which gives the real variable an initial value (a Radix-50 
constant) . 

For example, if a task name CCMFl is to be used in a system directive 
call, the task name could be defined and used as follows: 

DATA CCMF1/5RCCMF1/ 



CALL REQUES (CCMFl) 

Task names may also be defined during execution by using the IRAD50 
subroutine or the RAD50 function as described in the IAS/RSX-11 
FORTRAN IV User's Guide or the FORTRAN IV-PLUS User's Guide . 



1.5.1.3 Integer Arguments - All the subroutines described in this 
manual assume that integer arguments are INTEGER*2 type arguments. 
Both the FORTRAN IV and FORTRAN IV-PLUS systems normally treat an 
integer variable as one PDP-11 storage word, provided that its value 
is within the range -32768 to +32767. However, if the programmer 
specifies the /I4 option switch when compiling a program, particular 
care must be taken to ensure that all integer arguments used in these 
subroutines are explicitly specified as type INTEGER*2. 



1.5.1.4 GETADR Subroutine - Some subroutine calls include an argument 
described as an integer array. The integer array contains some values 
that are the addresses of other variables or arrays. Since the 
FORTRAN language does not provide a means of assigning such an address 
as a value,' programmers should use the GETADR subroutine described 
below. 

Calling Sequence: 

CALL GETADR(ipm, [argl] , [arg2] , . . . [argn] ) 

ipm is an array of dimension n. 

argl,... argn are arguments whose addresses are to be 

inserted in ipm. Arguments are inserted in the 
order specified. If a null argument is 
specified, then the corresponding entry in ipm 
is left unchanged. 

Example: 

DIMENSION IBUF(80) ,I0SB(2) ,IPARAM(6) 



CALL GETADR ( IPARAM ( 1) , IBUF (1 ) ) 

IPARAM(2)=80 

CALL QIO (IREAD,LUN,IEFLAG,IOSB, IPARAM, IDSW) 
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In this example, CALL GETADR enables the programmer to specify a 
buffer address in the CALL QIO directive (see Section 6.3.39). 



01^ 



1.5.2 The Subroutine Calls 

Table 1-1 is a list of the FORTRAN subroutine calls (and corresponding 
macro calls) associated with system directives (see Chapter 6 for 
detailed descriptions) . 

For some directives, notably Mark Time (CALL MARK) , both the. standard 
FORTRAN-IV subroutine call and the ISA standard call are provided. 
Other directives, however, are not available to FORTRAN tasks (for 
example. Specify Floating Point Exception AST [SFPA$] and Specify SST 
Vector Table For Task [SVTK$]). 



Table 1-1 
FORTRAN Subroutines and Corresponding Macro Calls 



Directive 


Macro Call 


FORTRAN Subrouti 


ne 


Abort Task 


ABRT$ 


CALL 


ABORT 




Alter Priority 


ALTP$ 


CALL 


ALTPRI 




Assign LUN 


ALUN$ 


CALL 


ASNLUN 




Attach Region 


ATRG$ 


CALL 


ATRG 




Cancel Time Based 


CRSQ$ 


CALL 


CANALL 




Initiation Requests 










Cancel Mark 


CMKT$ 


CALL 


CANMT 




Time Requests 










Clear Event Flag 


CLEF$ 


CALL 


CLREF 




Connect 


CNCT$ 


CALL 


CNCT 




Create Address Window 


CRAW$ 


CALL 


CRAW 




Create Group Global 


CRGF$ 


CALL 


CRGF 




Event Flags 










Create Region 


CRRG$ 


CALL 


CRRG 




Create Virtual' T^jrwlrtalh ;i : 


■■'::•:-: CRvf$;; ■■^'■^i- 


CALL 


CRVT 


IfFasly-fiS: 


Declare Significant Event 


DECL$S 


CALL 


DECLAR 




Disable AST Recognition 


DSAR$S 


CALL 


DSASTR 




Disable checkpointing 


DSCP$S 


CALL 


DISCKP 




Detach Region 


DTRG$ 


CALL 


DTRG 




Eliminate Address Window 


ELAW$ 


CALL 


ELAW 





(continued on next page) 
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Table 1-1 (Cont.) 
FORTRAN Subroutines and Corresponding Macro Calls 



Directive 



Eliminate Group Global 
Event Flags 

Eliminate Virtual Terminal 

Emit Status 

Enable AST Recognition 

Enable Checkpointing 

Exit If 

Exit With Status 

Extend Task 

Get LUN Information 

Get Mapping Context 

Get MCR Command Line 

Get Partition Parameters 

Get Region Parameters 

Get Sense Switches 

Get Task Parameters 
Get Time Parameters 



Macro Call 



ELGF$ 

ELVT$ 

EMST$ 

ENAR$S 

ENCP$S 

EXIF$ 

EXST$ 

EXTK$ 

GLUN$ 

GMCX$ 

GMCR$ 

GPRT$ 

GREG$ 

GSSW$S 

GTSK$ 
GTIM$ 



Inhibit AST Recognition 


IHAR$S 


Map Address window 


MAP$ 


Mark Time 


MRKT$ 


Queue I/O Request 


QIO$ 


Queue I/O Request And Wait 


QIOW$ 


Read All Event Flags 


RDAF$ 
RDXF$ 



FORTRAN Subroutine 



CALL ELGF 

CALL ELVT 

CALL EMST 

CALL ENASTR 

CALL ENACKP 

CALL EXITIF 

CALL EXST 

CALL EXTTSK 

CALL GETLUN 

CALL GMCX 

CALL GETMCR 

CALL GETPAR 

CALL GETREG 

CALL READSW 
CALL SSWTCH 

CALL GETTSK 

Several subroutines 
available (see the 
appropriate FORTRAN 
User's Guide) 

CALL INASTR 

CALL MAP 

CALL MARK 

CALL WAIT (ISA Standard 

call) 

CALL QIO 

CALL WTQIO 

CALL READEF (Only a 
single, local, common, or 
group-global event flag 
can be read by a FORTRAN 
task) 



(continued on next page) 
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Table 1-1 (Cont.) 
FORTRAN Subroutines and Corresponding Macro Calls 



^^^^ 



Directive 



Receive By Reference 
Receive Data 
Receive Data Or Exit 
Receive Data Or Stop 
I Remove Affinity 
r<>jquei3t 
Resume 
Run 

Send By Reference 

Send Data 

Send, Request And Connect 

Set Affinity 

Set Event Flag 

Spawn 

Specify Power Recovery AST 



Stop 

Stop For Logical OR of 
Event Flags 

Stop For Single Event Flag 

Suspend 

Task Exit 

Unmap Address Window 

Unstop 

Variable Receive Data 

Variable Receive Data Or Exit 



Macro Call 



RREF$ 

RCVD$ 

RCVX$ 

RCST$ 

RMAF$S 

RQST$ 

RSUM$ 

RUN$ 

$REF$ 
SDAT$ 
SDRC$ 
STAF$ 
SETF$ 
SPWN$ 
SFPA$ 



FORTRAN Subroutine 



CALL RREF 

CALL RECEIV 

CALL RECOEX 

CALL RCST 

CALL RMAF 

CALL REQUES 

CALL RESUME 

CALL RUN 

CALL START (ISA Standard 

call) 

CALL $REF 

CALL SEND 

CALL PDRC 

CALL liTAF 

CALL SETEF 

CALL SPAWN 

EXTERNAL SUBNAM 
CALL PWRUP (SUBNAM) 

(to establish an AST) 
CALL PWRUP 

(to remove an AST) 



STOP$S 


CALL 


STOP 


STLO$ 


CALL 


STLOR 


STSE$ 


CALL 


STOPFR 


SPND$S 


CALL 


SUSPEND 


EXIT$S 


CALL 


EXIT 


UMAP$ 


CALL 


UNMAP 


USTP$ 


CALL 


USTP 


VRCD$ 


CALL 


VHCD 


VRCX$ 


CALL 


VRCX 



(continued on next page) 



0m, 
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Table 1-1 (Cont.) 
B'ORTRAN Subroutines and Corresponding Macro Calls 



Directive 


Macro Call 


FORTRAN Subroutine 




Variable Receive Data Or Stop 


VRCS$ 


CALL VRCS 




Variable Send Datd 


VSDA$ 


CALL VSDA 




Wait For Single Event Flag 


WTSE$ 


CALL WAITFR 




Wait For Logical OR Of 


WTLO$ 


CALL WFLOR 




Event Flags 








Wait For Significant Event 


WSIG$S 


CALL WFSNE 





NOTE 

The following directives are not 
available as FORTRAN subroutines: 



Directive 



Macro Call 



AST Service Exit ASTX$S 

Connect To Interrupt Vector CINT$ 

Specify Floating Point SFPA$ 
Exception AST 

Specify parity Error AST SPEA$ 

Specify Receive By Reference AST SRRA$ 

Specify Receive Data AST SRDA$ 

Spocify Requesfcfd Exit AST SU;i|f?:; 

Specify SST Vector Table For SVDB$ 
Debugging Aid 

Specify SST Vector Table SVTK$ 
For Tasks 

Supervisor Call SCAL$S 



1.5.3 Error Conditions 

Each subroutine call includes an optional argument that specifies the 
integer to receive the Directive Status Word (ids). When a programmer 
specifies this argument, the subroutine returns a value that indicates 
whether the directive operation succeeded or failed. If the directive 
failed, the value indicates the reason for the failure. The possible 
values are the same as those returned to the' Directive Status Word 
(DSW) in MACRO-11 programs (see Appendix B) , except for the two ISA 
calls, CALL WAIT and CALL START. The ISA calls have positive numeric 
error codes (see Sections 6.3.38 and 6.3.50). 
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In addition, two types of error are r€iported by means of the FORTRAN 
Object Time System (OTS) diagnostic: messages. Both of these errors 
result in the termination of the task. The error conditions are: 

1. SYSTEM DIRECTIVE: MISSING ARGUMENT(S) 

This message indicates that at least one necessary argument 
was missing from a call to a system directive subroutine (OTS 
error number 100) . 

2. SYSTEM DIRECTIVE: INVALID EVENT FLAG NUMBER 

This message indicates that an event flag number in a call to 
WFLOR (Wait For Logical OR Of Event Flags) was not in the 
range 1 to 96 (OTS error number 101) . 



1.6 TASK STATES 

Many system directives cause a task to change from one state to 
another. There are two basic task states in RSX-llM/M-PLUS — dormant 
and active. The active state has three substates — ready-to-run, 
blocked, and stopped. ^0ttk 

The Executive recognizes the existence of a task only after it has 
been successfully installed and has an entry in the System Task 
Directory (STD) . (Task installation is the process whereby a task is 
made known to the system; see the RSX-llM/M-PLUS MCR Operations 
Manual.) Once a task has been installed, it is either dormant or 
active. These states are defined as follows: 

1. Dormant — Immediately follov/ing the processing of an Install 
command by the Monitor Console Routine, a task is known to 

the system, but is dormant. A dormant task has an entry in 0t^ 
the STD, but no request has been made to activate it. '; 

2. Active — A task is active from the time it is requested 
until the time it exits. Requesting a task means issuing the 
RQST$, RUN$, SPWN$, or SDRC$ macro, or an MCR Run command. 
An active task is eligible for scheduling, whereas a dormant 
task is not. 

The three substates of an active task are as follows: 

a. Ready-to-run — A ready-to-run task competes with other J^l^ 
tasks for CPU time on the basis of priority. The highest 

priority ready-to-run task obtains CPU time and thus 
becomes the current task. 

b. Blocked — A blocked task is unable to compete for CPU 
time for synchronization reasons or because a needed 
resource is not available. Task priority effectively 
remains unchanged, allowing the task to compete for memory 
space. 

c. Stopped — A stopped task is unable to compete for CPU 
time because of pending I/O completion, event flag(s) not 
set, or because the task stopped itself. When stopped, a 

task's priority effectively drops to zero and the task can ^ 

be checkpointed by any other task, regardless of that 

task's priority. if an AST occurs for the stopped task, 

its normal task priority is restored only for the duration 

of the AST routine execution; once the AST is completed, 

task priority returns to zero. ^^^ 
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1.6.1 Task State Transitions 

Dormant to Active - The following commands or directives cause the 
Executive to activate a dormant task: 

• A RUN$ directive 

• A ROST$ directive 

• A SPWN$ directive' 

• A SCRC$ directive 

• An MCR Run command 

Ready-to-Run to Blocked - The following events cause an active, 
ready-to-run task to become blocked: 

• A SPND$ directive 

• An unsatisfied Wait For condition 

• Checkpointing of a task out of memory by the Executive 

Ready-to-Run to Stopped - The following events cause an active, 
ready-to-run task to become stopped: 

• A STOP$S directive is executed, or an RCST$ or VRCS$ directive 
is issued when no data packet is available 

• Specified conditions for directive event flag STLO$ or STSE$ 
are not met 

e A checkpointable task issues a terminal input requestl 

Blocked to Ready-to-Run - The following events return a blocked task 
to the ready-to-run state: 

• A RSUM$ directive issued by another task 
« An MCR Resume command 

• A Walt For condition is satisfied 

• The Executive reads a checkpointed task into memory 

Stopped to Ready-to-Run - The following events return a stopped task 
to the ready-to-run state, depending upon how the task became stopped: 

• A task stopped via the STOP$S, RCST$ , or VRCSS directive 
becomes unstopped via USTP$ directive execution. 

• A task stopped for buffered . I/O becomes unstopped on 
completion of the requested I/O transaction. 

• A task stopped for an event flag (or flags) becomes unstopped 
when the specified event flag (or flags) becomes (or become) 
set. 



1 Only in systems that support the checkpointing of tasks during 

terminal input. A task can be stopped for buffered I/O only when not 

at AST state, the task is checkpointable, and the region in which I/O 
is being done to/from is checkpointable. 
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• An MCR Unstop command is issued. 

• Terminal input for a checkpointable task completes. 1 

Active to Dormant - The following events cause an active task to 
become dormant: 

• An EXIT$S, EXIF$, RCVX$ , or VRCX$ directive, or a RREF$ 
directive that specifies the exit option 

• An ABRT$ directive 

• An MCR Abort command 

• A Synchronous System Trap (SST) for which a task has not 
specified a service routine 



1.6.2 Removing an Installed Task 

To remove an installed task from the system, the user issues the MCR 
Remove command from a privileged terminal. Refer to the 
RSX-llM/llM-PLUS MCR Operations Manual . 



1.7 THE GENERAL INFORMATION DIRECTIVE 

The General Information Directive is used by some of DIGITAL'S 
software modules to obtain information from Executive data structures 
without being directly mapped to the Executive. Since this directive 
may change from release to release of RSX-llM/M-PLUS, it is 
specifically not documented in this manual. However, advanced users 
desiring to use this directive can refer to module DRGIN.MAC and macro 
GIN$ in the Executive macro library. Although the directive may 
operate in the same manner in future releases, its operation is 
specifically not guaranteed, and users are cautioned accordingly. 



1.8 DIRECTIVE RESTRICTIONS FOR NONPRIVILEGED TASKS 

Certain Executive directives cannot be issued by nonpr ivileged tasks, fi^k 
except as listed below: 

Directive Macro Call Comments 

Abort Task ABRT$ In systems that support 

multiuser protection, a 
nonpr ivileged task can only 
abort tasks with the same ,, 

TI: as the task issuing the 
directive . 



1 Only in systems that support the checkpointing of tasks during 
terminal input. 
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Directive 



Macro Call 



Comments 



Alter Priority 



ALTP$ 



In systems that support 
multiuser protection, a 
nonpr ivileged task can only 
alter its own priority to 
values less than or equal to 
the task's installed 
priority. 



Cancel Time Based CSRQ$ 
Initiation Requests 



Cannot be issued by a 
nonpr ivileged task in 
systems that support 
multiuser protection except 
for tasks with the same TI: 
as the issuing task. 



Connect To interrupt CINT$ 
Vector 



Cannot be issued by a 
nonpr ivileged task in mapped 
systems. 



1.9 RSX-ilM-PLUS 

RSX-llM-PLU£l supports multiprocessor PDP-11 system configurations and 
provides additional Executive services on all PDP-li systemo in which 
RSX-llM-PLUS system softwdre has been installed. Kxecutive services 
include additional parent-offspring tasking support, Supervisor mode 
library support, CPU/UNIDUG affinity, exit and parity error AST 
routine support, and Executive-level dispatching. A detailed list of 
RSX-liyi-PlUS Executive services is provided in Chapter b. 
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CHAPTER 2 
SIGNIFICANT EVENTS, SYSTEM TRAPS, AND STOP-BIT SYNCHRONIZATION 



This chapter introduces the concept of significant events and 
describes the ways in which a programmer can make use of event flags, 
synchronous and asynchronous system traps, and stop-bit 
synchronization. 



2.1 SIGNIFICANT EVENTS 

A significant event is a change in system status that causes the 
Executive to reevaluate the eligibility of all active tasks to run. A 
significant event is usually caused (either directly or indirectly) by 
a system directive issued from within a task. Significant events 
include the following: 

• An I/O completion 

• A task exit 

• The execution of a Send Data directive (see Section 6.3.52) 

• The execution of a Send By Reference or a Receive By Reference 
directive (see Sections 6.3.62 and 6.3.48) 

• The execution of an Alter Priority directive (see Section 
6.3.2) 

• The removal of an entry from the clock queue (for instance, 
resulting from the execution of a Mark Time directive or the 
issuance of a rescheduling request) 

• The execution of a Declare Significant Event directive (see 
Section 6.3.15) 

• The execution of the round-robin scheduling algorithm at the 
end of a round-robin scheduling interval 

• The execution of an Exit, an Exit With Status, or an Emit 
Status directive 



2.2 EVENT FLAGS 

Event flags are a means by which tasks recognize specific events. 
(Tasks also use Asynchronous System Traps (ASTs) to recognize specific 
events. See Section 2.3.3.) In requesting a system operation (such as 
an I/O transfer) , a task may associate an event flag with the 
completion of the operation. When the event occurs, the Executive 
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sets the specified flag. Several examples later in this section 
describe how tdsks can use event flags to coordinate task execution. 

Ninety-six event flags are available to enable tasks to distinguish 
one event from another. Each event flag has a corresponding unique 
Event Flag Number (EFN) . Numbers 1 through 32 form a group of flags 
that are unique to each task and are set or cleared as a result of 
that task's operation. Numbers 33 through 64 form a second group of 
flags that are common to all tasks, hence their name "common flags." 
Common flags may be set or cleared as a result of any task's 
operation. The last eight flags in each group, local flags (25-32) 
and common flags (57-64), are reserved for use by the system. Numbers 
65 through 96 form the third group of flags, known as "group-global 
event flags." These flags can be used in any application where common 
event flags can be used; however, they can only be used by tasks 
running under UICs containing the group code specified when the 
group-global event flags were created., Three directives (Create Group 
Global Event Flags, Eliminate Group Global Event Flags and Read 
Extended Event Flags) provide the Executive support for implementing 
group-global event flags. 

Tasks can use the common flags for intertask communication or their 
own local event flags internally. The setting, clearing, and testing 
of event flags can be performed by using Set Event Flag (SETF$) , Clear 
Event Flag (CLEF$) , and Read All Event Flags (RDAF$) directives. (The 
Read All Event Flags directive will not return the group-global event 
flags. When these flags are in use, read all event flags using the 
Read Extended Event Flags (RDXF$) directive.) 

Programmers must take great care when setting or clearing event flags, 
especially common flags. Erroneous or multiple setting and clearing 
of event flags can result in obscure software faults. A typical 
application program can be written without explicitly accessing or 
modifying event flags, since many of the directives can implicitly 
perform these functions. The Send Data (SDAT$) , Mark Time (MRKT$) , 
and the I/O operations directives can all implicitly alter an event 
flag. 

Examples 1 and 2 below illustrate the use of common event flags 
(33-64) to synchronize task execution. Examples 3 and 4 illustrate 
the use of local flags (1-32). 

Example 1 

Task B clears common event flag 35 and then blocks itself by 
issuing a Wait For directive that specifies common event flag 35. 

Subsequently another task. Task A, specifies event flag 35 in a 

Set Event Flag directive to inform Task B that it may proceed. 

Task A then issues a Declare Significant Event directive to 

ensure that the Executive will schedule Task B. 

Example 2 

In order to synchronize the transmission of data between Tasks A 
and B, Task A specifies Task B and common event flag 42 in a Send 
Data directive. 

Task B has specified flag 42 in a Wait For directive. When Task 
A's Send Data directive has caused the Executive to set flag 42 
and to cause a significant event. Task B proceeds and issues a 
Receive Data directive because its Wait For condition has been 
satisfied . 
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Example 3 

A task contains a Queue I/O Request directive and an associated 
Wait For directive; both directives specify the same local event 
flag. When the task queues its I/O request, the Executive clears 
the local flag. If the requested I/O is incomplete when the task 
issues the Wait For directive, the Executive blocks the task. 

When the requested I/O has been completed, the Executive sets the 
local flag and causes a significant event. The task then resumes 
its execution at the instruction that follows the Wait For 
directive. Using the local event flag in this manner ensures 
that the task does not manipulate incoming data until the 
transfer is complete. 

Example 4 

A task specifies the same local event flag in a Mark Time and an 
associated Wait For directive. When the Mark Time directive is 
issued, the Executive first clears the local flag and 
subsequently sets it when the indicated time interval has 
elapsed . 

If the task issues the Wait For directive before the local flag 
has been set, the Executive blocks the task, which resumes when 
the flag is set at the end of the proper time interval. 

Specifying an event flag does not mean that a Wait For directive must 
be issued. Event flag testing can be performed at any time. The 
purpose of a Wait For directive is to stop task execution until an 
indicated event occurs. Hence, it is not necessary to issue a Wait 
For directive immediately following a Queue I/O Request directive or a 
Mark Time directive. 

If a task issues a Wait For directive that specifies an event flag 
that is already set, the blocking condition is immediately satisfied 
and the Executive immediately returns control to the task. 



Tasks can issue Stop For Logical OR Of Event Flags directives instead 
of Wait For directives. When this is done, an event flag condition 
not satisfied will result in the task being stopped instead of being 
blocked until the event flag(s) is/are set. 

The simplest way to test a single event flag is to issue the directive 
CLEF$ or SETF$. Both these directives can cause the following return 
codes: 

IS.CLR - Flag was previously clear 

IS. SET - Flag was previously set 

For example, if a set common event flag indicates the completion of an 
operation, a task can issue the CLEF$ directive both to read the event 
flag and simultaneously to reset it for the next operation. If the 
event flag was previously clear (the current operation was 
incomplete), the flag remains clear. 



2.3 SYSTEM TRAPS 

System traps are transfers of control (also called software 
interrupts) that provide tasks with a means of monitoring and reacting 
to events. The Executive initiates system traps when certain events 
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occur. The trap transfers control to the task associated with the 
event and gives the task the opportunity to service the event by 
entering a user-written routine. 

There are two kinds of system traps: 

• Synchronous System Traps (SSTs) — SSTs detect events directly 
associated with the execution of program instructions. They 
are synchronous because they always recur at the same point in 
the program when trap-causing instructions occur. For 
example, an illegal instruction causes an SST. 

• Asynchronous System Traps (ASTs) — ASTs detect events that 
occur asynchronously to the task' s .execution. That is, the 
task has no direct control over the precise time that the 
event, hence, the trap, may occur. The completion of an I/O 
transfer may cause an AST to occur, for example. 

A task that uses the system trap facility issues system directives 
that establish entry points for user-written service routines. Entry 
points for SSTs are specified in a single table. AST entry points are 
set by individual directives for each kind of AST. When a trap 
condition occurs, the task automatically enters the appropriate 
routine (if its entry point has been specified). 



2.3.1 Synchronous System Traps (SSTs) 

SSTs can detect the execution of: 

• Illegal instructions 

• Instructions with invalid addresses 

• Trap instructions (TRAP, EMT, lOT, BPT) 

• FIS floating-point exceptions (PDP-11/40 only) 

The user can set up an SST vector table, containing one entry per SST 
type. Each entry is the address of an SST routine that services a 
particular type of SST (a routine that services illegal instructions, 
for example) . When an SST occurs, the Executive transfers control to 
the routine for that type of SST. If a corresponding routine is not 
specified in the table, the task is aborted. The SST routine enables 
the user to process the failure and then return to the interrupted 
code. Note that if a debugging aid and the user's task both have an 
SST vector enabled for a given condition, the debugging aid vector is 
referenced first to determine the service routine address. 

SST routines must always be reentrant because an SST can occur within 
the SST routine itself. Although the Executive initiates SSTs, the 
execution of the related service routines is indistinguishable from 
the task's normal execution. An AST or another SST can therefore 
interrupt an SST routine. 



2.3.2 SST Service Routines 

The Executive initiates SST service routines by pushing the task's 
Processor Status (PS), Program Counter (PC), and trap-specific 
parameters onto the task's stack. After removing the trap-specific 
parameters, the service routine returns control to the task by issuing 
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an RTI or RTT instruction. Note that the task's general purpose 
registers R0-R6 are not saved. If the SST routine makes use of them, 
it must save and restore them itself. 

To the Executive, SST routine execution is indistinguishable from 
normal task execution, so that all directive services are available to 
an SST routine. An SST routine can remove the interrupted PS and PC 
from the stack and transfer control anywhere in the task; the routine 
does not have to return control to the point of interruption. 
However, programmers should remember that any operations performed by 
the routine (such as the modification of registers or the DSW, or the 
setting or clearing of event flags) remain in effect when the routine 
eventually returns control to the task. 

A trap vector table within the task contains all the service routine 
entry points. The user specifies the SST vector table by means of the 
Specify SST Vector Table For Task directive or the Specify SST Vector 
For Debugging Aid directive. The trap vector table has the following 
format: 

word Odd or nonexistent memory address error (Also, on 
some PDP-11 processors for example, PDP-11/45 an 
illegal instruction traps here rather than through 
word 04.) 

word 1 Memory protect violation 

word 2 T-bit trap or execution of a BPT instruction 

word 3 Execution of an IDT instruction 

word 4 Execution of a reserved instruction 

word 5 Execution of a non-RSX EMT instruction 

word 6 Execution of a TRAP instruction 

word 7 Synchronous floating-point exception (PDP-11/40 only) 

A zero appearing in the table means that no entry point is specified. 
An odd address in the table causes an SST to occur when another SST 
tries to use that particular address as an entry point. If an SST 
occurs and an associated entry point is not specified in the table, 
the Executive aborts the task. 

Depending on the reason for the SST, the task's stack may also contain 
additional information, as follows: 

Memory protect violation (complete stack) 

SP + 10 — PS 

SP+06 — PC 

SP+04 — Memory protect status register (SRO)l 

SP+02 — Virtual PC of the faulting instruction (SR2)1 

SP+00 — Instruction backup register (SRl)l 

TRAP instruction or EMT other than 377 (and 376 in the case of 
unmapped tasks and mapped privileged tasks) (complete stack) 

SP+04 — PS 



1 For details of SRO, SRI, and SR2, see the section on the memory 
management unit in the appropriate PDP-11 Processor Handbook. 
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SP+02 — PC 

SP+00 — Instruction operand (low-order byte) multiplied by 2, _ 

non-sign-extended ^^i^ 

All items except the PS and PC must be removed from the stack before 
the SST service routine exits. 



2.3.3 Asynchronous System Traps (ASTs) 

The primary purpose of an AST is to inform the task that a certain 
event has occurred, for example, the completion of an I/O operation. 
As soon as the task has serviced the event, it can return to the 
interrupted code. ^ 

Some directives can specify both an event flag and an AST; with these 
directives, ASTs can be used as an alternative to event flags or the 
two can be used together. This capability enables the user to specify 
the same AST routine for several directives, each with a different 
event flag. Thus, when the Executive passes control to the AST 
routine, the event flag can determine the action required. i09lki 

AST service routines must save and restore all registers used. If the 
registers are not restored after an AST has occurred, the task's 
subsequent execution may be unpredictable. 

Although not able to distinguish execution of an SST routine from task 
execution, the Executive is aware that a task is executing an AST 
routine. An AST routine can be interrupted by an SST routine, but not 
by another AST routine. 

The following notes describe general characteristics and uses of ASTs: i*H^ 

• If an AST occurs while the related task is executing, the task 
is interrupted so that the AST service routine can be 
executed . 

• If an AST occurs while another AST is being processed, the 
Executive queues the latest AST (First-In-First-Out or FIFO) 
and then processes the next AST in the queue when the current 
AST service is complete (unless AST recognition was disabled 
by the AST service routine) . 

• If a task is suspended when an associated AST occurs, the task 
remains suspended after the AST routine has been executed, 
unless it is explicitly resumed either by the AST service 
routine itself, or by another task (the MCR Resume command, 
for example) . 

• If an AST occurs while the related task is waiting for an 
event flag to be set (a Wait For directive) , the task 
continues to wait after execution of the AST service routine 
until the AST service routine itself or another task sets the 
appropriate event flag. 

• If an AST occurs for a checkpointed task, the Executive queues 
the AST (FIFO), brings the task into memory, and then 
activates the AST when the task returns to memory. 

When a checkpointed task is brought back into memory, the 

Executive issues an AST for the task if its receive queue 

contains one or more entries. This practice prevents ggmj^ 

checkpointed tasks from losing receive ASTs. _^^fls 
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• If a task is stopped when an AST occurs, it becomes unstopped 
for the AST and becomes stopped after the AST routine has been 
executed. The stopped task can be explicitly unstopped either 
by the AST service routine itself, by another task, or by an 
MCR command. 

• An optional RSX-llM feature that is always in RSX-llM-PLUS 
allows the checkpointing of tasks during terminal input. When 
this feature is included, the Executive stops the execution of 
a checkpointable task when the terminal driver receives an 
input request for the task. The task resumes execution when 
the terminal input has finished. A stopped task can execute 
an AST service routine if an AST occurs; . but the task remains 
stopped after the routine finishes unless the terminal input 
has finished in the meantime. Note, however, that an AST 
routine itself can reactivate the stopped task by issuing an 
I/O Kill function for the task's terminal input request. 

• The Executive allocates the necessary dynamic memory when an 
AST is specified. Thus, no AST condition lacks dynamic memory 
for data storage when it actually occurs. 

• Two directives. Disable AST Recognition and Enable AST 
Recognition, allow ASTs to be queued for subsequent execution 
during critical sections of code. (A critical section might 
be one that accesses data bases also accessed by AST service 
routines, for example.) If ASTs occur while AST recognition is 
disabled, they are queued (FIFO) and then processed when AST 
recognition is enabled. 



2.3.4 AST Service Routines 

When an AST occurs, the Executive pushes the task's Wait For mask 
word, the DSW, the PS, and the PC onto the task's stack. This 
information saves the state of the task so that the AST service 
routine has access to all the available Executive services. The 
preserved Wait For mask word allows the AST routines to establish the 
conditions necessary to unblock the waiting task. Depending on the 
reason for the AST, the stack may also contain additional parameters. 
Note that the task's general purpose registers R0-R6 are not saved. 
If the routine makes use of them, it must save and restore them 
itself. 

The Wait For mask word comes from the offset H.EFLM in the task's 
header. Its value and the event flag range to which it corresponds 
depend on the last Wait For Single Event Flag or Wait For Logical OR 
Of Event Flags directive issued by the task. For example, if the last 
such directive issued was Wait For Single Event Flag 42, the mask word 
has a value of 1000(8) and the event flag range is from 33 to 48. Bit 
of the mask word represents flag 33, bit 1 represents flag 34, and 
so on. 

The Wait For mask word is meaningless if the task has not issued 
either type of Wait For directive. 

After processing an AST, the task must remove the trap-dependent 
parameters from its stack; that is, everything from the top of the 
stack down to, but not including, the task's Directive Status Word. 
It must then issue an AST Service Exit directive with the stack set as 
indicated in the description of that directive (see Section 6.3.4). 
When the AST service routine exits, it returns control to one of two 
places: another AST, or the original task. 
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There are eleven variations on the format of the task's stack, as 
follows: 

1. If a task needs to be notified when a Floating Point 
Processor exception trap occurs, it issues a Specify Floating 
Point Processor Exception AST directive. If the task 
specifies this directive, an AST will occur when a Floating 
Point Processor exception trap occurs. The stack will 
contain the following values: 

SP+12 — Event flag mask word 

SP+10 — PS of task prior to AST 

SP+06 — PC of task prior to AST 

SP+04 — Task's Directive Status Word 

SP+02 — Floating exception code 

SP+00 — Floating exception address 

NOTE 

Refer to the appropriate Processor 
Handbook for a description of the FPU 
exception code values. 

2. If the task needs to be notified of power failure recoveries, 
it issues a Specify Power Recovery AST directive. An AST 
will then occur when the power is restored if the task is not 
checkpointed . The stack will contain the following values: 

SP+06 — Event flag mask word 

SP+04 — PS of task prior to AST 

SP+02 — PC of task prior to AST 

SP+00 — Task's Directive Status Word 

3. If a task needs to be notified when it receives either a 
message or a reference to a common area, it issues either a 
Specify Receive Data AST or a Specify Receive By Reference 
AST directive. An AST will occur when the message or 
reference is sent to the task. The stack will contain the 
following values: 

SP+06 — Event flag mask word 

SP+04 — PS of task prior to AST 

SP+02 — PC of task prior to AST 

SP+00 — Task's Directive Status Word 

4. When a task queues an I/O request and specifies an 
appropriate AST service entry point, an AST will occur upon 
completion of the I/O request. The task's stack will contain 
the following values: 

SP+10 — Event flag mask word 
SP+06 — PS of task prior to AST 
SP+04 — PC of task prior to AST 
SP+02 — Task's Directive Status Word 

SP+00 — Address of I/O status block for I/O request 
(or zero if none was specified) 

5. When a task issues a Mark Time directive and specifies an 
appropriate AST service entry point, an AST will occur when 
the indicated time interval has elapsed. The task's stack 
will contain the following values: 
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SP+10 — Event flag mask word 
SP+06 — PS of task prior to AST 
SP+04 — PC of task prior to AST 
SP+02 — Task's Directive Status Word 

SP+00 — Event flag number (or zero if none was 
specified) 

6. An offspring task, connected via a Spawn, Connect, or Send, 
Request And Connect directive, returns status to the 
connected (parent) task(s) upon exit via the Exit AST. The 
parent task's stack contains the following values: 

SP+10 — Event flag mask word 

SP+06 — PS of task prior to AST 

SP+04 — PC of task prior to AST 

SP+02 — Task's Directive Status Word 

SP+00 — Address of exit status block 

7. If a parent task issues a Create Virtual Terminal directive, 
the input and output AST routines are entered with the task's 
stack containing the following values: 

SP+14 — Event flag mask word 

SP+12 — PS of task prior to AST 

SP+10 — PC of task prior to AST 

SP+06 — Task's Directive Status Word 

SP+04 — Third parameter word (Vertical Format 

Control - VFC) of the offspring request 
SP+02 — Byte count of offspring request 
SP+00 — Virtual terminal unit number (low byte); I/O 

Eubfunction code of offspring request (high 

byte) 

8. IE the Attach/Detach AST routine is entered for a virtual 
terminal attach, the task's stack contains the following 
values : 

SP+14 — Event flag p.ask word 

SP+12 — PS of task prior to AST 

SP+10 — PC of task prior to AST 

SP+06 — Task's Directive Status Word 

SP+04 — Second word of offspring task name 

SP+02 — First word of offspring task name 

SP+CO — Virtual terminal unit number (low byte); I/O 

subfunction code of offspring request (high 

byte) 

If Che Attach/Detach AST routine is entered for a virtual 
terminal detach, the task's stack contains the following 
val jes: 

SP+14 — Event flag mask word 

SP+12 — PS of task prior to AST 

SP+10 — PC of task prior to AST 

SP+06 — Task's Directive Status Word 

SP+04 — Second word of offspring task name = 

SP+02 — First word of offspring task name = 

sp+00 — virtual terminal unit number (low byte) ; I/O 

subfunction code of offspring request (high 

byte) 
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SP+34 :;i^,jqo:n tents of ymemory:: parltii': csRt 

SP+32 ;:/itHai?dwa re-dependent irtformation) 

SP+30 -■ ■' ■ ■■■ ■ .^- - 

SP+26 — 

SP+24 — 

SP+22 — 

SP+20 — 

SP+16 — 

SP+14 — , 

SP+1 2 — f :Dc)'0§nt;s:i^of;';c:ach:e;.cont^ i ster 

SP+10 — : (jioti-t^rtits ;Oii mempiry; systfenir- er register 

SP+06 --.;C:;|>rifeents; bf; high error Miiifaess register 

SP+04 — :;-qprtfent:s:b:f: jlpwerrpr addr^^^ register 

SP+02 — rpirocesisor ; ia&ntif icatiort :(s^ processor system=0) 

SP+00 — rwumiset^of ;by to clean the stack (52) 

LO. If a taskKbecprnfeSi-^JDorld pr MCR when the 

Specify ; iRieijt^est^d ;;:EKit;Oi;-ABT;::V^^ effect, the abprt AST is 

entered With :-;the::Vt;ask''s stack: j^^ the following 

values: :-'i:t;!l:i''r- ■■'■ :■''■':''■;'.= :■ 



SP+06:-, •::T'*^:':;Eveht: :f lag mask:,,W6*d5 

sp+fl|.;:;;trt--', ;:,ps..'b:f- task-- pr ibt^.to last 
sp+{)|'\":|.-:-:ji-ipdi--p:f - task .--pr lQ:r-:-fcp: %5t 
SP+p0|;r:;--;-/;:Ta)sl<''s: Di:r^:ctijy|e4isia«:us word 

11. If a task issues a QIO 10. ATA function to the full-duplex 
terminal driver, unsolicited terminal input will cause AST 
service routine entry with the task's stack containing the 
following values: 

SP+10 — Event flag mask word r 

SP+06 — PS of task prior to AST 

SP+04 — PC of task prior to AST 

SP+02 — Task's Directive Status Word 

SP+00 — Unsolicited character in low byte; parameter 

2 in the high byte ^^ 
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2.4 STOP-BIT SYNCHRONIZATION 

Stop-bit synchronization allows tasks to be checkpointed during 
terminal input or while waiting for an event to occur. (For example, 
an event flag to become set or an Unstop directive to become ; issued.) 
Synchronization between tasks can be controlled through the setting of 
the task's Task Control Block (TCB) stop bit. 

When the task's stop bit is set, the task is blocked from further 
execution, its priority for memory allocation effectively drops to 
zero, and it may be checkpointed by any other task in the system, 
regardless of priority. If checkpointed, the task remains out of 
memory until its stop bit is cleared, at which time the task becomes 
unstopped, its normal priority for memory allocation becomes restored, 
and it is considered for memory allocation based on the restored 
priority. 

If the stopped task receives an AST, it becomes unstopped until it 
exits the AST routine. Memory allocation for the task during the AST 
routine is based on the task's priority prior to the stopped state. 
Note that a task cannot be stopped when an AST is in progress, but the 
AST routine can issue either an Unstop or Set Event Flag directive to 
reference the task, causing it to remain unstopped after it issues the 
AST Service Exit directive. 

There are three ways in which a nonpr ivileged task can become stopped 
and corresponding ways to become unstopped. Only one method for 
stopping a task can be applied at a time. 

1. A task can stop itself for buffered I/O by issuing an input 
request to tho terminal driver, or, if it is an K5X-11M-PLUG 
offsprino task, it can be stopped by issuing either an input 
or output request to tiic virtual terminal driver. The tas.-; 
can only be unstopped by the completion of the buffered I/O 
request. 

2. A task can be stopped for event flag{s) by issuing the Stop 
For Single Event Flag directive or the Stop For Logical OR Of 
Event Flags directive. In this case, the task can only be 
unstopped by setting the specified event flag(s). 

3. A task can be stopped by issuing a Stop or the Receive Or 
Stop directive. In this case, the task can only be unstopped 
by issuing the Unstop directive. 

A task cannot be stopped when an AST is in progress (AST state) . Any 
directives that can cause a task to become stopped are illegal at the 
AST state. If buffered I/O requests occur when the task is at the AST 
state, the driver does not stop the task or buffer its I/O if the 
request is dequeued. 

When a task is stopped for any reason at the task state, it can still 
receive ASTs. If the task has been checkpointed, it becomes eligible 
for entrance back into memory when an AST is queued for it. The task 
retains its normal priority in memory while it is at the AST state or 
has ASTS queued. Once it has exited the AST routine with no other 
ASTs queued, the task is again stopped and effectively has zero 
priority for memory allocation. 

Six directives can be used for stop-bit synchronization: 

• Stop - This directive stops the issuing task and cannot be 
issued at the AST state. 
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• Receive Data Or Stop and Variable Receive Data Or Stop - These 
directives attempt to dequeue send data packets from the ^^ 
specified task (or any task if none is specified) . If there f^^ 
is no such packet to be dequeued, the issuing task is stopped. 

These directives cannot be issued at the AST state. 

• Stop For Logical OR Of Event Flags - This directive stops the 
issuing task until the specified flags in the specified group 
of local event flags become set. If any of the specified 
event flags are already set, the task does not become stopped. 
This directive cannot be issued at the AST state. 

• Stop For Single Event Flag - This directive stops the issuing 
task until the indicated local event flag becomes set. If the 
specified event flag is already set, the task does not become ' 
stopped. This directive cannot be issued at the AST state. 

• Unstop - This directive unstops a task that has become stopped 
via the Stop or Receive Or Stop directive. 



.4^^^ 



■OTTF^^P** 



mtis 
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CHAPTER 3 
MEMORY MANAGEMENT DIRECTIVES 



Within the framework of memory management directives, this chapter 
discusses the concepts of extended logical address space, regions, and 
virtual address windows. 



3.1 ADDRESSING CAPABILITIES OF AN RSX-llM TASK 

Without overlaying of tasks, an RSX-llM task cannot explicitly refer 
to a location with an address greater than 177777 (32K words). The 
16-bit word size of the PDP-11 imposes this restriction on a task's 
addressing capability. Overlaying a task means that it must first be 
divided into segments: a single root segment, which is always in 
memory, and any number of overlay segments, which can be loaded into 
memory as required. Unless an RSX-llM task uses the memory management 
directives described in this chapter, the combined size of the task 
segments concurrently in memory cannot exceed 32K words. 

When resident task segments cannot exceed a total of 32K words, a task 
requiring large amounts of data must access data that reside on disk. 
Data are disk-based not only because of limited memory space but also 
because transmission of large amounts of data between tasks is only 
practical via disk. An overlaid task, or a task that needs to access 
or transfer large amounts of data, incurs a considerable amount of 
transfer activity over and above that caused by the task's function. 

Task execution could obviously be faster if all or a greater portion 
of the task were resident in memory at run time. RSX-llM includes a 
group of memory management directives that provide the task with this 
capability. The directives overcome the 32K-word addressing 
restriction by allowing the task to dynamically change the physical 
locations that are referred to by a given range of addresses. With 
these directives, a task can increase its execution speed by reducing 
its disk I/O requirements, at the expense of increased physical memory 
requirements. 

r\r^\r iihii riTMc nr^rti'c /-lan Q^f*ir'ris;^i\/ ^^oLibls the memorv availabiC tor 
tasks on PDP-11 systems that are capable of operating in Supervisor 
mode through the use of Supervisor mode library routines. Supervisor 
mode library routines are instruction-only routines that are napped 
into Supervisor mode I-space (up to 32K words maximum) . User task 
parameters, stack, and any locations that may be written are mapped 
into Supervisor mode D-space (up to 32K words maximum) . 
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3.1.1 Address Happing 

In a mapped system, the user does not need to know where a task 
resides in physical memory. Mapping, the process of associating task 
addresses with available physical memory, is transparent to the user 
and is accomplished by the KTll memory management hardware. (See the 
appropriate PDP-11 Processor Handbook for a description of the KTll.) 
When a task references a location (virtual address) , the KTll 
determines the physical address in memory. The memory management 
directives use the KTll to perform address mapping at a level that is 
visible to and controlled by the user. 



3.1.2 Virtual and Logical Address Space 

The two concepts defined below, virtual address space and logical 
address space, provide a basis for understanding the functions 
performed by the memory management directives: 

• Virtual Address Space — A task's virtual address space 
corresponds to the 32K-word address range imposed by the 
PDP-ll's 16-bit word length. The task can divide its virtual 
address space into segments called virtual address windows 
(see Section 3.2) . 

• Logical Address Space — A task's logical address space is the 
total amount of physical memory to which the task has access 
rights. The task can divide its logical address space into 
various areas called regions (see Section 3.3). Each region 
occupies a contiguous block of memory. 

If the capabilities supplied by the RSX-llM memory management 
directives were not available, a task's virtual address space and 
logical address space would directly correspond; a single virtual 
address would always point to the same logical location. Both types 
of address space would have a maximum size of 32K words. However, the 
ability of the memory management directives to assign or map a range 
of virtual addresses (a window) to different logical areas (regions) 
enables the user to extend a task's logical address space beyond 32K 
words. 



3.1.3 Supervlsor:;M<jd^":Addressl;ng ■■ 

KSX-llM-PLUS suppoHs PDP-ij; processors :; capable of operating in 
Supervisor mode. : :The iSupervisoir mbde is" ^^^^^^ of three possible modes 
(User, Kernel, aMdiSuperviSor) ihwhlcin those systems can operate. In 
User mode, eight .active ■■ page registers ;:(APRe) are available for 
address mapping of user : tasks. : Note that: only I-space APRS are 
employed in User mode ,foir both instructions -and data. 

Supervisor mode ijuppprt -doubles the instrucfcion space available to 
tasks. This is becaiisie sixteen -AJPRS:, (eight User mode I-space and 
eight Supervisor mode I-space) : are available >f or address napping. The 
contents of User imodey I-space APRS are Copied into Supervisor mode 
D-space APRS to ali.9w;-Sape to access User mode 

data. (Refer to cithie:: appropriate PDP^ll Processor Handbook for a 
complete description: of address mapping , memory management, and the 
various APR registers). 



^jmii, 
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3.2 VIRTUAL ADDRESS WINDOWS 

In order to manipulate the mapping of virtual addresses to various 
logical areas, the user must first divide a task's 32K of virtual 
address space into segments. These segments are called virtual 
address windows. Each window encompasses a continuous range of 
virtual addresses, which must begin on a 4K word boundary (that is, 
the first address must be a multiple of 4K) . The number of windows 
defined by a task can vary from 1 to 7 (as discussed below, window 
is not available to the user) . The size of each window can range from 
a minimum of 32 words to a maximum of 32K. 

A task that includes directives to manipulate address windows 
dynamically must have window blocks set up in its task header. The 
Executive uses window blocks to identify and describe each currently 
existing window. When linking the task, the programmer specifies the 
required number of window blocks to be set up by the Task Builder (see 
the RSX-llM/M-PLUS Task Builder Reference Manual ) . The number of 
blocks should equal the maximum number of windows that will exist at 
any one time when the task is running. 

A window's identification is a number from to 7 ilMpJlBitoilr'tiiRt 
rSu|?ei;yls,pr,- ,wi_nd6Ws),v, which is an index to the window's corresponding 
window block. the address window identified by is the window that 
maps the task's header and root segment. The Task Builder 
automatically creates window 0, which is mapped by the Executive and 
cannot.be specified in any directive. 

Figure 3-1 shows the virtual address space of a task divided into four 
address windows (windows 0, 1, 2, and 3). The shaded areas indicate 
portions of the address space that are not included in any window (9K 
to 12K and 23K to 24K) . Addresses that fall within the ranges 
corresponding to the shaded areas cannot be used. 

When a task uses memory management directives, the Executive views the 
relationship between the task's virtual and logical address space in 
terms of windows and regions. Unless a virtual address is part of an 
existing address window, reference to that address will cause an 
illegal address trap to occur. Similarly, a window can be mapped only 
to an area that is all or part of an existing region within the task's 
logical address space (see Section 3.3). 

Once a task has defined the necessary windows and regions, it can 
issue memory management directives to perform operations such as the 
following : 

• Map a window to all or part of a region. 

• Unmap a window from one region in order to map it to another 
region. 

• Unmap a window from one part of a region in order to map it to 
another part of the same region. 

NOTE 

It is currently possible for a task with 
outstanding I/O to unmap from a region 
(although it cannot detach from 
it — see Section 3.3.2). Because this 
feature may be impossible to support in 
future releases of the system, it is 
recommended that users consider 
carefully before designing an 
application based on this capability. 
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Figure 3-1 Virtual Address Windows 



3.3 REGIONS 

A region is a portion of a physical memory to which a task has (or 
potentially may have) access to. The current window-to-region mapping 
context determines that part of a task's logical address space that 
the task can access at one time. A task's logical address space can 
consist of various «types of regions: 

• Task Region — A contiguous block of memory in which the task 
runs. 

• Static Common Region — An area defined by an operator at run 
time or at system generation time, such as a global common 
area. 

• Dynamic Region — A region created dynamically at run time by 
issuing the memory management directives. 

• Sharable Region — A read-only portion ot multiuser tasks that 
are in sharable regions (RSX-llM-PLUS only). 



■^^^T^i 
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Tasks refer to a region by means of a region ID returned to the task 
by the Executive. Region ID always refers to a task's task region. 
Region ID 1 always refers to the read-only (pure code) portion of 
multiuser tasks. All other region IDs are actually addresses of the 
attachment descriptor maintained by the Executive in the system 
dynamic storage area. 

Figure 3-2 shows a sample collection of regions that could make up a 
task's logical address space at some given time. The header and root 
segment are always part of the task region. Since a region occupies a 
contiguous area of memory, each region is shown as a separate block. 

Figure 3-3 illustrates a possible mapping relationship between the 
windows and regions shown in Figures 3-1 and 3-2. 



3.3.1 Shared Regions 

Address mapping not only extends a task's logical address space beyond 
32K words, it also allows the space to extend to regions that have not 
been linked to the task at task-build time. One result is an 
increased potential for task interaction by means of shared regions. 
For example, a task can create a dynamic region to accommodate large 
amounts of data. Any number of tasks can then access that data by 
mapping to the region. Another result is the ability of tasks to use 
a greater number of common routines. Thus, tasks can map to required 
routines at run time, rather than linking to them at task-build time. 



3.3.2 Attaching to Regions 

Attaching is the process by which a region becomes part of a task's 

logical address space. A task can map only a region that is part of 

the task's logical address space. There are three ways to attach a 
task to a region: 

1. All tasks are automatically attached to regions that are 
linked to them at task-build time. 

2. A task can issue a directive to attach itself to a named 
static common region or a named dynamic region. 

3. A task can request the Executive to attach another specified 
task to any region within the logical address space of the 
requesting task. 

Attaching identifies a task as a user of a region and prevents the 

system from deleting a region until all user tasks have been detached 

from it. (It should be noted that fixed tasks do not automatically 
become detached from regions upon exiting.) 
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Figure 3-2 Regions 
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Figure 3-3 Mapping Windows to Regions 
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3.3.3 Region Protection 

A task cannot indiscriminately attach to any region. Each region has 
a protection mask to prevent unauthorized access. The mask indicates 
the types of access (read, write, extend, delete) allowed for each 
category of user (system, owner, group, world). The Executive checks 
that the requesting task's User Identification Code (UIC) allows it to 
make the attempted access. The attempt fails if the protection mask 
denies that task the access it wants. 

To determine when tasks can attach to regions outside their logical 
address space, the following points must be considered. (Note that 
all considerations presume there is no protection violation.): 

• Any task can attach to a named dynamic region, so long as it 
knows the name. In the case of an unnamed dynamic region, a 
task can attach to the region only after receiving a Send By 
Reference directive from the task that created the region. 

• Any RSX-JIM-PLUS task can issue a Send By Reference directive 
to attach another task to any region. RSX-llM tasks can do 
the same thing except that the task region itself may not be 
one of the regions involved. The reference sent includes the 
access rights with which the receiving task attaches to the 
region. The sending task can only grant access rights that it 
has itself. 

• Any task can map to a named static common region. 
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3.4 DIRECTIVE SUMMARY 

This section briefly describes the function of each memory management 
directive. 



3.4.1 Create Region Directive (CRRG$) 

The Create Region directive creates a dynamic region in a designated 
system-controlled partition and optionally attaches the issuing task 
to it (see Section 6.3.12). 



3.4.2 Attach Region Directive (ATRG$) 

The Attach Region directive attaches the issuing task to a static 
common region or to a named dynamic region (see Section 6.3.5). 



3.4.3 Detach Region Directive (DTRG$) 

The Detach Region directive detaches the issuing task from a specified 
region. Any of the task's address windows that are mapped to the 
region are automatically unmapped (see Section 6.3.18). 



3.4.4 Create Address Window Directive (CRAW$) 

The Create Address Window directive creates an address window, 
establishes its virtual address base and size, and optionally maps the 
window. Any other windows that overlap with the range of addressesof 
the new window are first unmapped and then eliminated (see Section 
6.3.10) . 



3.4.5 Eliminate Address Window Directive (ELAW$) 

The Eliminate Address Window directive eliminates an existing address 
window, unmapping it first if necessary (see Section 6.3.19). 



3.4.6 Map Address Window Directive (MAP$) 

The Map Address Window directive maps an existing window to an 
attached region. The mapping begins at a specified offset from the 
start of the region and goes to a specified length. If the window is 
already mapped elsewhere, the Executive unmaps it before carrying out 
the map assignment described in the directive (see Section 6.3.37). 



3.4.7 Unmap Address Window Directive (UMAP$) 

The Unmap Address Window directive unmaps a specified window. After 

the window has been unmapped, its virtual address range cannot be 

referenced until the task issues another mapping directive (see 
Section 6.3.70) . 



3-9 



MEMORY MANAGEMENT DIRECTIVES 



3.4.8 Send By Reference Directive (SREF$) 



The Send By Reference directive inserts a packet containing a <^% 
reference to a region into the receive queue of a specified task. The 
receiver task is automatically attached to the region referred to (see 
Section 6.3.62) . 



3.4.9 Receive By Reference Directive (RREF$) 

The Receive By Reference directive requests the Executive first to 
select the next packet from the receive-by-reference queue of the 
Issuing task, and then to make the information in the packet available 
to the task. Optionally the directive can map a window to the 
referenced region or cause the task to exit if the queue does not 
contain a receive-by-reference packet (see Section 6.3.48). 



3.4.10 Get Mapping Context Directive (GMCX$) 

The Get Mapping Context directive causes the Executive to return to ' 

the issuing task a description of the current window-to-region mapping 
assignments. The description is in a form that enables the user to 
restore the mapping context through a series of Create Address Window 
directives (see Section 6.3.31). 



3.4.11 Get Region Parameters Directive (GREG$) 

The Get Region Parameters directive causes the Executive to supply the <i^^ 

issuing task with information about either its task region (if no ' 

region ID is given) or an explicitly specified region (see Section 
6.3.33) . 



3.5 USER DATA STRUCTURES 

Most memory management directives are individually capable of 
performing a number of separate actions. For example, a single Create 
Address Window directive can unmap and eliminate up to seven 
conflicting address windows, create a new window, and map the new 
window to a specified region. The complexity of the directives 
requires a special means of communication between the user task and 
the Executive. The communication is achieved through data structures 
that: 

• allow the task to specify which directive options it wants the 
Executive to perform 

• permit the Executive to provide the task with details about 
the outcome of the requested actions 

There are two types of user data structures that correspond to the two 
key elements (regions and address windows) manipulated by the 
directives. The structures are called: 

• The Region Definition Block (RDB) 

• The Window Definition Block (WDB) 
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Every memory management directive, except Get Region Parameters, uses 
one of these structures as its communications area between the task 
and the Executive. Each directive issued includes in the Directive 
^mr^' Parameter Block (DPB) a pointer to the appropriate definition block. 
Symbolic address offset values are assigned by the task, pointing to 
locations within an RDB or a WDB. The task can change the contents of 
these locations to define or modify the directive operation. After 
the Executive has carried out the specified operation, it assigns 
values to various locations within the block to describe the actions 
taken and to provide the task with information useful for subsequent 
operations. 



3.5.1 Region Definition Block (RDB) 

Figure 3-4 illustrates the format of an RDB. In addition to the 
symbolic offsets defined in the diagram, the region status word, 
R.GSTS, contains defined bits that may be set or cleared by the 
Executive or the task. (RSX-llM reserves undefined bits for future 
expansion.) The bits and their definitions follow. 

Bit Definition 

RS.CRR=100000 Region was successfully created. 

RS.UNM=40000 At least one window was unmapped on a detach. 

RS.MDL=200 Mark region for deletion on last detach. 

RS.NDL=100 Created region is not to be marked for 

deletion on last detach. 

RS.ATT=40 Attach to created region. 

RS.NEX=20 Created region is not extendable. 

RS.DEL=10 Delete access desired on attach. 

RS.EXT=4 Extend access desired on attach. 

RS.WRT=2 Write access desired on attach. 

RS.RED=1 Read access desired on attach. 

The three memory management directives that require a pointer to an 
RDB are: 

Create Region (CRRG$) 
Attach Region (ATRG$) 
Detach Region (DTRG$) 

When a task issues one of these directives, the Executive clears the 
four high-order bits in the region status word of the appropriate RDB. 
After completing the directive operation, the Executive sets the 
RS.CRR or RS.UNM bit to indicate to the task what actions were taken. 
The other bits are never modified by the Executive. 
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Figure 3-4 Region Definition Block 



3.5.1.1 Using Macros to Generate an RDB - RSX-llM provides two 

macros, RDBDF$ and RDBBK$, to generate and define an RDB. RDBDF$ 

defines the offsets and status word bits for a region definition 

block; RDBBK$ then creates the actual region definition block. The 
format of RDBDF$ is: 

RDBDF$ 

Since RDBBK$ automatically invokes RDBDF$, the programmer need only 
specify RDBBK$ in a module that creates an RDB. The format of the 
call to RDBBK$ is: 



where 



RDBBK$ siz,nam,par ,sts,pro 

siz = the region size in 32-word blocks 

nam = the region name (RAD50) 

par = the name of the partition in which to create the region 
(RAD50) 
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bit definitions of the region status word 
the region's default protection word 



The sts argument sets specified bits in the status word R.GSTS. The 
argument normally has the following format: 

<bitl [1 . ..Ibitn]> 

where bit is a defined bit to be set. 

The argument pro is an octal number. The 16-bit binary equivalent 
specifies the region's default protection as follows: 



Bits 15 



12 11 



8 7 



4 3 



WORLD 



GROUP 



OWNER 



SYSTEM 



Each of the four categories above has four bits, with each bit 
representing a type of access: 



3 


2 


1 





DELETE 


EXTEND 


WRITE 


READ 



Bit 



A bit value of zero indicates that the specified type of access is to 
be allowed; a bit value of one indicates that the specified type of 
access is to be denied. 

The macro call: 

RDBBK$ 102., ALPHA, GEN, <RS.NDL IRS. ATT J RS.WRT!RS.RED>, 167000 

expands to: 



.WORD 





• WORD 


102. 


.RAD50 


/ALPHA/ 


.RAD50 


/GEN/ 


.WORD 





.WORD 


RS.NDLIRS.ATTIRS.WRTIRS.RED 


.WORD 


167000 



If a Create Region directive pointed to the RDB defined by this 
expanded macro call, the Executive would create a region 102 (decimal) 
32-word blocks in length, named ALPHA, in a partition named GEN. The 
defined bits specified in the sts argument tell the Executive: 

• Not to mark the region for deletion on the last detach 

• To attach region ALPHA to the task issuing the directive macro 
call 

• To grant read and write access to the attached task 

The protection word specified as 167000 (octal) assigns a default 
protection mask to the region. The octal number, which has a binary 
equivalent of 1110111000000000, grants all types of access to system 
and owner tasks (0000) , and read access only to group and world tasks 
(1110) . 

If the Create Region directive is successful, the Executive will first 
return to the issuing task a region ID value in the location accessed 
by symbolic offset R.GID, and then will set the defined bit RS.CRR in 
the status word R.GSTS. 
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3.5.1.2 Using FORTRAN to Generate an RDB - FORTRAN programmers must 
create an 8-word, single-precision integer array as the RDB to be 
supplied in the subroutine calls: 

CALL ATRG (Attach Region directive) 
CALL CRRG (Create Region directive) 
CALL DTRG (Detach Region directive) 

(See the PDP-11 FORTRAN Language Reference Manual for information on 
the creation of arrays.) An RDB array has the following format: 

Word Content s 

irdb(l) Region ID 

irdb(2) Size of the region in 32-word blocks 

irdb(3) Region name (2 words in Radix-50 format) 
irdb(4) 

irdb(5) Name of the partition that contains the region 
irdb(6) (2 words in Radix-50 format) 

i'^db(7) Region status word (see the paragraph following 
this list) 

irdb(8) Region protection code 

The FORTRAN programmer modifies the region status word, irdb(7), by 
setting or clearing the appropriate bits. See the list in Section 
3.5.1 that describes the defined bits,. The bit values are listed 
alongside the symbolic offsets. 

Note that Hollerith text strings can be converted to Radix-50 values 
by calls to the FORTRAN library routine IRAD50 (see the appropriate 
FORTRAN User's Guide). 






3.5.2 Window Definition Block (WDB) 

Figure 3-5 illustrates the format of a WDB. The block consists of a 

number of symbolic address offsets to specific WDB locations. One of 

the locations is the window status word, W.NSTS, which contains 0*^ 

defined bits that can be set or cleared by the Executive or the task. 

(RSX-llM reserves all undefined bits for future expansion.) The bits 

and their definitions follow. 

Bit Definition 

WS.CRW=100000 Address window was successfully created. 

WS.UNM=40000 At least one window was unmapped by a Create "^ 

Address Window, Map Address Window, or Unmap 
Address window directive. 

WS.ELW=20000 At least one window was eliminated in a 

Create Address Window or Eliminate Address » 

Window directive. 

WS.RRF=10000 Reference was successfully received. 

WS.NBP=4000 Do not bypass the cache (for multiprocessor _ 

systems) . ^^ 
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Bit 
WS.RES=2000 
WS.NAT=1000 



WS.64B=400 

WS.MAP=200 
WS.RCX=100 

ws.s:s=40 

WS.BPS=20 

ws.db:l=io 

WS.EXT=4 
WS.WRT==2 

WS.RED==1 



Definition 

Map only if resident. 

Create attachment descriptor only if 
necessary (for Send By Reference directives). 

Defines the task's permitted alignment 
boundaries — for 256-word (512-byte) 
alignment, 1 for 32-word (64-byte) alignment. 

Window is to be mapped in a Create Address 
Window or Receive By Reference directive. 

Exit if no references to receive. 

Create window in Supervisor I-space. 

Always bypass the cache for this window (for 
multiprocessor systems) . 

Send with delete access. 

Send with extend access. 

Send with write access or map with write 
access. 

Send with read access. 



Array 
Element 



iwdb (1) 



iwdb (2) 



iwdb (3) 



iwdb (7) 



iwdb (8) 



Symbolic 
Offset 



W.NID 
W.NAPR 



W.NBAS 



W.NSIZ 



iwdb (4) W.N RID 



iwdb (5) W.NOFF 



iwdb (6) W.NLEN 



W.NSTS 



W.NSRB 



Block Format 



BASE APR 



WINDOW ID 



VIRTUAL BASE ADDRESS (BYTES) 



WINDOW SIZE (32W BLOCKS) 



REGION ID 



OFFSET IN REGION (32W BLOCKS) 



LENGTH TO MAP (32W BLOCKS) 



WINDOW STATUS WORD 



SEND/RECEIVE BUFFER ADDRESS (BYTES) 



Byte 
Offset 




10 



12 



14 



16 



Figure 3-5 Window Definition Bloclc 
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The following directives require a pointer to a WDB: 

Create Address Window (CRAW$) 
Eliminate Address Window (ELAW$) 
Map Address Window (MAP$) 
Unmap Address Window (UMAP$.) 
Send By Reference (SREF$) 
Receive By Reference (RREF$) 

When a task issues one of these directives, the Executive clears the 
four high-order bits in the window status word of the appropriate WDB. 
After completing the directive operation, the Executive can then set 
any of these bits to tell the task what actions were taken. The other 
bits are never modified by the Executive. 



3.5.2.1 using Macros to Generate a WDB - RSX-llM provides two macros, 
WDBDF$ and WDBBK$, to generate and define a WDB. WDBDF$ defines the 
offsets and status word bits for a window definition block; WDBBK$ 
then creates the actual window definition block. The format of WDBDF$ 
is: 

WDBDF$ 

Since WDBBK$ automatically invokes WDBDF$ , the programmer need only 
specify WDBBK$ in a module that generates a WDB. The format of the 
call to WDBBK$ is: 

WDBBK$ apr,siz,rid,off,len,sts,srb 

where 

apr = a number from to 7 that specifies the window's base 
Active Page Register (APR) . The APR determines the 4K 
boundary on which the window is to begin. APR 
corresponds to virtual address 0, APR 1 to 4K, APR 2 to 
8K, and so on. 

siz = the size of the window in 32-word blocks 

rid = a region ID 

off = the offset within the region to be mapped, in 32-word 
blocks 

len = the length within the region to be mapped, in 32-word 
blocks 

sts = the bit definitions of the window status word 

srb = a send/receive buffer virtual address 

The argument sts sets specified bits in the status word W.NSTS. The 
argument normally has the following format: 

<bitl[! . . .!bitn]> 

where bit is a defined bit to be set. 



.4^hi 
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The macro call: 

WDBBK$ 5, 76., 0,50., ,<WS .MAP 1 WS .WRT> 



expands to: 



• BYTE 


0,5 


.WORD 





.WORD 


76. 


.WORD 





.WORD 


50. 


.WORD 





• WORD 


WS.MAPIWS.WRT 


.WORD 






(Window ID returned in low-order byte) 
(Base virtual address returned here) 



If a Create Address Window directive pointed to the WDB defined by the 
macro call expanded above, the Executive would: 

• Create a window 76 (decimal) blocks long beginning at APR 5 
(virtual address 20K or 120000 octal) 

• Map the window with write access (<WS.MAP!WS .WRT>) to the 
issuing task's task region (because the macro call specified 
for the region ID) 

• Start the map 50 (decimal) blocks from the base of the region 
and map an area either equal to the length of the window (76 
[decimal] blocks) or the length remaining in the region, 
whichever is smaller (because the macro call defaulted the len 
argument) 

• Return values to the symbolic W.NID (the window's ID) and 
W.NBAS (the window's virtual base address) 



3.5.2.2 using FORTRAN to Generate a WDB - FORTRAN programmers must 
create an 8-word, single-precision integer array as the WDB to be 
supplied in the subroutine calls: 

CALL CRAW (Create Address Window directive) 

CALL ELAW (Eliminate Address Window directive) 

CALL MAP (Map Address Window directive) 

CALL UNMAP (Unmap Address Window directive) 

CALL SREF (Send By Reference directive) 

CALL RREF (Receive By Reference directive) 

(See the PD P-11 FORTRAN Language Reference Manual for information on 
the creat'Ioii of arrays.) A WDB array has the following* format: 

Contents 

Bits to 7 contain the window ID; bits 8 to 15 
contain the window's base APR 

Base virtual address of the window 

Size of the window in 32-word blocks 

Region ID 

Offset length within the region at which map 
begins, in 32-word blocks 



Word 
iwdb(l) 

iwdb(2) 
iwdb(3) 
iwdb(4) 
iwdb(5) 
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Word 
iwdb(6) 
iwdb(7) 

iwdb(8) 



Contents 



Length mapped within the region in 32-word blocks 

Window status word (see the paragraph following 
this list) 

Address of send/receive buffer 



The FORTRAN programmer modifies the window status word, iwdb(7), by 

setting or clearing the appropriate bits. See the list in Section 

3.5.2 that describes the defined bits,, The bit values are listed 
alongside the symbolic offsets. 



Note that 



The contents of bits 8 to 15 of iwdb(l) must normally be set 
without destroying the value in bits to 7 for any directive 
other than Create Address Window. 

A call to GETADR (see Section 1.5.1.4) can be used to set up 
the address of the send/receive buffer. For example: 

CALL GETADR (IWDB, ,,,,,, ,]:RCVB) 

This call places the address of buffer IRCVB in array elcsment 
8. The remaining elements are unchanged. The subroutines 
SREF and RREF also set up this value. 



4«l% 



3.5.3 Assigned Values or Settings 

The exact values or settings assigned to individual fields within the 
RDB or the WDB vary according to each directive. Fields that are not 
required as input can have any value v/hen the directive is issued. 
Chapter 6 describes which offsets and settings are relevant for each 
memory management directive. The values assigned by the task are 
called input parameters; those assigned by the Executive are called 
output parameters. 



3.6 PRIVILEGED TASKS 

When a privileged task maps to the Executive and the I/O page, the 
system normally dedicates five or six APRs to this mapping. A 
privileged task can issue memory management directives to remap any 
number of these APRs to regions. Programmers should take great care 
when using the directives in this way. Such remapping can cause 
obscure bugs to occur. When a directive unmaps a window that formerly 
mapped the Executive or the I/O page, the Executive restores the 
former mapping. 
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CHAPTER 4 
PARENT/OFFSPRING TASKING 

4.1 PARENT/OFFSPRING TASKING SUPPORT OVERVIEW 

Parent/offspring tasking has many real-time applications in 
establishing and controlling complex interrelationships between parent 
and offspring tasks. A parent task is one that starts or connects to 
another task, called an offspring task. A major application for the 
parent-offspring task relationship is batch processing, when running 
tasks in this manner, task relationships and parameters can be set up 
on line to control the processing of a batch job (or jobs) that run 
off line. 

Starting (or activating) offspring tasks is called "spawning". 
Spawning also includes the ability to establish task communications; 
a parent task can be notified when an offspring task exits and can 
receive status information from the offspring task. 

Status returned from an offspring task to a parent task indicates 
successful completion of the offspring task or identifies specific 
error conditions. 



4.2 DIRECTIVE SUMMARY 

4.2.1 Parent/Offspring Tasking Directives 

Three directives can connect a parent task to an offspring task: 

• Spawn - This directive requests activation of, and connects 
to, a specific offspring task. 

An offspring task that is spawned by a parent task has the 
following three task functions that are not provided by the 
Request or Run directive. 

1. A spawned offspring task can be a command line interpreter 
(CLI). 

2. A spawned offspring task in an RSX-llM-PLUS system can 
have a virtual terminal as its terminal input device 
(TI:) . 

3. A spawned offspring task can return current status 
information or exit status information to a connected 
parent task or tasks. 
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Spawn directive options include: 

1. Queuing a command line for the offspring task (which may 
be a command line interpreter). 

2. Establishing t:he of fspring task's TI: as a physical 
terminai,: of, in RSX-llK-'PLUS;; systems, as a previously 
created : virtual terminal un it. r ■ 

3. For privileged tasks in BSX-IIM-PLUS systems, designating 
any terthinal as the offspring Tlr; 

• Connect - This directive establishes task communications for 
synchronizing with the exit status OC emit status issued by a 
task that is already active. 

• Bend, Request And Connect - This RSXrilM-PLUS directive sends 
data to the, specified task, requests activation of the task if 
it is not already active, and connects to the task. 

A parent task can connect to more than one offspring task using the 
Spawn and Connect directives, as appropriate. In addition, the parent 
task can use the directives in any combination to multiply connect to 
offspring tasks. 

An offspring task can be connected to multiple parent tasks. An 
appropriate data structure, the Offspring Control Block, is produced 
(in addition to those already present) each time a parent task 
connects to the offspring task. 
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4.2.2 Task Communication Directives 

Two directives in an offspring task return status to connected parent 
tasks: 

• Exit With Status - This directive in an offspring task causes 
the offspring task to exit, passing a status word to all 
connected parent tasks (one or more) that have been previously 
connected via a Spawn, Connect, or, ;iri RSX-llM-PLUS systems. 
Send, liRequest: And Connect : directive. 

• Emit Statiis-: This RSX-llM-PLUS difectiye causes the offspring 
task :;:t6: ipass a status word to either the specified connected 
task 6r all connected parent tasks if no task is explicitly 

speqlfiled.;:;:;--."^:;-.;;..- ■ : ' 

When status is passed to tasks in this manner, the parent task(s) no 
longer remains connected. 

Offspring task status values that can be returned to parent tasks are 
listed as follows: 



Symbol 
EX$WAR 

EX$SUC 
EX$ERR 



value 
Returned 



Meaning 

Warning - task succeeded, 
irregularities are possible 



but 



Success - results should be as expected 

Error - results are unlikely to be as 
expected 



4-2 



PARENT/OFFSPRING TASKING 

Value 
Symbol Returned Meaning 

EX$SEV 4 Severe Error - one or more fatal errors 

detected, or task aborted 



4.3 CONNECTING AND PASSING STATUS 

Offspring task exit status can be returned to connected (parent) 
task(s) by issuing the Exit With Status directive. In addition, 
RSX-llM-PLUS offspring tasks can return status to one or r.ore 
connected parent tasks at any time by issuing the Emit Status 
Directive. Mote that only connected parent-offspring tasks can pass 
status. 

The means by which a task connects to another task are 

indistinguishable once the connect process is complete. For example, 

Task A can become connected to Task B in one of the three ways shown 
below. 

1. Task A spawned Task B when Task B was inactive. 

2. Task A connected to Task B when Task B was active. 

3. Task A issued a Send, Request And Connect to Task B when Task 
B was either active or inactive. 

Regardless of the way in which Task A became connected to Task B, Task 
B can pass status information back to Task A, set the event flag 
specified by Task A, or cause the AST specified by Task A to occur in 
any of the five ways shown below. Note that once offspring task 
status is returned to one or more parent tasks, the parent tasks 
become disconnected. 

1. Task B issues a normal (successful) exit directive. Task A 
receives a status of EX$SUC. 

2. Task B is aborted. Task A receives a severe error status of 
EX$SEV. 

3. Task B issues an Exit With Status directive, returning status 
to Task A upon completion of Task B. 

4. Task B issues an Lmit Status directive specifying Task A. If 
Task A is multiply connected to Task h , the OCBs that contain 
information about those Multiple connects are stored in a 
FIFO queue. The first OCb is used to determine which event 
f lac , AST address, and exit status block to use. 

5. Tdsl! B issues an Emit Status directive to all connected tasks 
(no task tiaine specified). 

When a task has previously specified another task in a Spawn, Connect, 
or S^nd, Request And Connect directive and then exits, and if status 
has not yet been returned, the OCB representing this connect remains 
queued, but is marked to indicate that the parent task has exited. 
When this OCB is subsequently dequeued due to an Emit Status 
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directive, or any type of exit, no action is taken since the parent 
task has exited. This procedure is followed to help a 
multiply-connected task to keep in synchronization when parent tasks 
unexpectedly exit. 

Examples of directive usage for intertask synchronization are provided 
below (macro call form for directives are shown) . Task A is the 
parent task and Task B is the offspring task. 



^^^ft. 



Task A 



Task B 



Action 



SPWN$ 
CNCT$ 
SDRC$ 



GDRC$, 
USTP$ 



EXST$ 
EXST$ 



RCVX$ , 
EMST$ 



RCST$, 
EKSTS 



SDAT$, RCST$ 
USTP$ 



Task A spawns Task B. Upon Task B completion. 
Task B returns status to Task A. 

Task A connects to active Task B. Upon Task B 
completion. Task B returns status to Task A. 

Ta^k A sends data to Task B, requests Task B if It 
is presently not active, and connects to Task B. 
Task B receivels the -data, does some processing 
based on the data, returns status to Task A 
(possibly setting an : e^i^ent flag or declaring an 
-AST):, and becomes disconnected from Task A. 

Task A: sendis data to TasK-B-;/ ^ Task B if it 
is iiresently not active >cg^^ to Task B, and 
UrtstopS: Task B. Task Bbe^ unstopped (if Task 
B previously could not: de<3ueUG the data packet), 
receives the data, does sbtnc processing based on 
:the data; and returns status: to Task A (possibly 
:: setting an event flag -ijr, declaring an AST). 

Task A queues a data packet for Task B and unstops 
Task B; Task B receives the data. 



JI^H|^^ 
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CHAPTER 5 
RSX-llM-PLUS EXECUTIVE DIRECTIVES AND FUNCTIONS 

5.1 RSX-llM-PLUS DIRECTIVES — OVERVIEW 

This chapter introcuces additional Executive directives provided in 
RSX-LIM-PLUS for parent/offspring tasking support, Supervisor mode 
library support, CfU/UNIBUS affinity support, and exit (abort) and 
parity error AST routine support. A s'umnary of these directives is 
snown in Tabla 5-1. 



Table 5-1 
P.SX-llM-PLUtj Executive Directives 



Directive 


Function 


Sead, Request 


Parent/offspring task spawing 


And Connect 




Emit Status 


Parent/offspring task communication 


Create Virtual Terminal 


Provide non-interactive terminal 


1 Eliminate virtua: Terminal 


I/O £3upport for offspring tasks 


Set Affinity 


Select CPU and UNI3US run(s) used 


Remove Affinity 


for task execution 


Supervisor Call 


Supervisor mode library support 


Receive Variable Data 




Receive Variable Data 




Or Stop 


Vnriable-length send/receive 


Receive Variable Data 


buffer support 


Or Exit 




Send Variable Daia 




Specify Requested Exit AST 


Specily AST routine address 


Specify Parity Error AST 
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5.2 VIRTUAL TiSRMINAI. SUPPORT 



5.2.1 Virtual Terminal Functiorvs 

Offspring t^sks can perform I/O operations With virtual terminals in 
the same manner as they can perform I/O with physical terminals, A 
virtual terminal is :not a physical (hardware) device; it is 
implemented in software with data structures created by the Executive. 

Virtual terminals are not interactive. That is, an operator does not 
issue requests or receive prompts and data In aih immediate interaction 
between the operator, the terminal, and the running task. Thus, 
virtual termirials are used in hatch processing and other off-line 
processing environments to provide terminal I/Q support for offspring 
tasks that dp rtpt require operator intervention. 

The parent task 'Creates the data structure for the virtual terminal by 
issuing the Create Virtual Terminal directive^ A parameter (vtun) in 
the Spawn directive allows the parent task to specify the virtual 
terminal unit number for use as the offspring task's TI:. Parent 
tasks are notified of of fspring task virtual terminal requests via 
parent task AST ro^itihes. 

If the parent task exits or aborts without issuing an Eliminate 
Virtual Terminal directive for each virtual terminal it has created, 
the Sx;ecueive responds in two ways: 

:;i. it -marks for deallocation all virtual terminals the 

:: aborting task has created.; For each virtual terminal 

^; :: u^^^ of tasks using the 

virtual terminal unit as Tit. As each of these tasks 

"exit, the count is reduced until it reaches zero, at which 

i;;: point the virtual terminal unit is deallocated . 

2.: It -aborts all nonprivileged tasks using the virtual 

:termihai: units are marked for deallocation as Tl:. 

HOwevfer, privileged tasks in the same situation are not 
■ ab6.rted> . ^ ■■ ■ 
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5.2.2 yittuai Terminal Support— Directive Summary 

Virtual termihai support is provided by two directives; 

• , Create vi r tual 
;/T/-structure'..y for 
■■.><3ey.i-ce;-:l.ist.,.-a 
.■■■■^^CyTJ'?: "unlf.' 

direetive, the 

is returned 

count in the i 
:■■:. that ■. ■.the";'.ta§ 

eliniin^t^^ if 
task issues ah 
^ th i s unit numb 



Terminal - This directive 


creates 


the data 


a virtual terminal unit and 


links it 


into the 


sslgning the lowest available 


virtual 


terminal 


niamber. Upon successful completion 


of this 


assigned unit number for the 


virtual 


terminal 


in the DSW with the Carry bit 


clear. 


A rundown 


ssuing task's TCB is incremented to 


indicate 


k is a parent of a virtual terminal tha 


t must be 


the task exits. The count is 


reduced 


if the 


Eliminate virtual Terminal di 


rective specifying 


er..- 







Direqt^^^ include AST addresses at which input 

requ^stiS and output requests are serviced, an AST address at 
which the parent task is notified of pfispring attach/detach 
requests to the virtual terminal unit, and maximum buffer 
length allowed for of f spring: I/O requests. 
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Eliminate Virtual Terminal - This directive marks the 
specLfied virtual terminal unit data structures for 
deallocation. Processing this directive results in the 
virtual terminal becoming unlinked from the device list and 
deallocated. Note that this directive can only be issued by 
the task that created the virtual terminal device unit being 
elim.lnated. Active offspring tasks are aborted whose TI: 
device units are the virtual terminal being eliminated; in 
systems that support multiuser protection, only nonpr ivileged 
tasks are aborted in this manner. Upon successful completion 
of this directive, the rundown count in the parent task's TCB 
is reduced to reflect the current number of virtual terminals 
it has created. 



5.3 SUPERVISOR MODE LIBRARY SUPPORT 

Supervisor mode library support allows memory mapping of large 
Lnstruction-only libraries to double the address space available to 
user tasks. Since the increased address space requires few (if any) 
overlays, faster program execution and decreased program development 
and task-build tine result. 

Executive support of Supervisor mode libraries is relatively 
transparent to the user. When running in the Supervisor mode, all of 
the User mode mapping is in Supervisor data space. Thus, User mode 
routines tnat accept parameters or pointers to parameters, in 
registers or via low-core impure area pointers, can receive these 
parameters in the same manner when running in either User mode or 
3up<3rvisor mode. 

Supervisor routines return to the caller via the Return (RTS PC) 
instruction in the same manner as User mode routines. Transparency is 
naintained to the extent that the same library routine may be mapped 
oimul taneous Ly by one task in U&er mode and by another task in 
Supervisor mode. 

Executive support for Supervisor mode libraries is provided by the 
Supervisor Call directive. This directive requires, as parameters, 
the target PC in the library, and the PC of a completion routine, 
which is also in the library. Return from Supervisor node to User 
mode is via an RT] instruction; therefore, a completion routine is 
required to propagate the condition codes back to the caller. 

NOTE 

The normal use of the Supervisor call 
directive is via Task Builder-supplied 
run-tine routines. The call is made in 
much the same way as disk- or 
memory-resident overlays are referenced, 
that is, via an AUTOLOAD vector. Refer 
to the RSX-llM/M-PLUS Task Builder 
Manual for a description of building and 
referencing Supervisor node libraries. 

When writing subroutines to be included in a Supervisor mode library, 
the following conditions nust be observed: 

1. Supervisor mode library routines must not require call 
parameters to be pushed on the stack before, the call . 
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2. Parameters may be passed in registers or pointed to by 
registers other than the SP; ^^^ 

3. Supervisor::mode library routines must have no local data. 
When executing, they are in a separately mapped instruction 
space. Data references will be directed to the calling (User 
mode) task.: Refer to the appropriate Processor Handbook for 
a description of the addressing process for a particular 

system. . , 

4. No disk- br; memory-resident overlays may be initiated while 
executing /-the Supervisor mode library routine. Memory 
management ■; directives may be issued, however, if the 
Supervisor mode library routine inaintains all relevant data 
structures;! in the user task area. : ■ 

5. Although a completion routine is provided that will propagate 
all four^ condition codes back to the caller, the return to 
User mode is more: efficient if the library routine uses only 
the C-bit Condition code. 

6. The format pf the Supervisor Call directive is reserved by j'^% 
DIGITAL and is subject to change. Users are cautioned to use 

only the: supplied macro if they {choose to issue the 
Supervisor Call directive instead :pfLising the task builder 
run-time routines. : 

A Supervisor mode ;, library ■ routine can initiate asynchronous 1/0 

requests with AST addresses in ;either: the Supervisor mode library or 

in the User mode task. If the I/O request: is /issued while executing 

in a Supervisor mode library, the specified AST address is considered 

to be a Supervisor: mode library address. J If the I/O request is issued 

while executing in the user task, the specified AST address is ^^,,^ 

considered a task address^ 



5.4 TASK CPU/UNIBUS AFFINITY 

Task CPU/UNIBUS affinity enables a : task :to select which CPU and UNI3US 
run(s) to use for task execution when running on PDP-11 multiprocessor 
systems. The programmer must be completely -aware of the particular 
system hardware configuration in which the': task will be executed 
before using these directives. 

Task CPU/UNIBUS affinity can be established at three possible times: 

1. When thejtask is instalied 

2. When the task is mapped into a device partition (which 
must have CPU/UNIBUS run affinity previously established) 

3. When set by the Set Affinity directive 

When issued, the Set Affinity directive prdduoes; an affinity mask word 
that defines task CPU/UNIBUS affinity. One bit Ln the word is set to 
select one CPU on which the task will be run. : One or more of twelve 
additional bits can be : set to select one or more UNIBUS runs for 
peripheral device use during task; execution. 

Two directives supj^ort task affinity, as follows? 

• Set Affinity -r This directive accepts parameters that define 
the CPU and UNIBUS run mask for task execution. All 
parameters are::ORed at assembly time to form a one-word naak. 
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Remove Affinity - This directive removes task CPU/UNIBUS 
affinity previously established by a Set Affinity directive. 



5.5 EXIT AST ROUTINE SUPPORT 

Exit AST routine support is provided by the Specify Requested Exit AST 
directive. This directive allows program control to pass to a 
specified AST routine when a task is aborted by directive or MCR. 
This can be most useful for program cleanup before terminating. 

Privileged and nonpr ivileged task are not handled by this directive in 
exactly the same manner. Whenever a privileged task in which a 
Specify Requested Exit AST directive has been issued is aborted, the 
tpecifiod AST routine is entered, regardless of how many times the 
task was previously aborted. However, nonpr ivileged tasks can enter 
the speci::ied AST routine only once; subsequent aborts result in the 
task exiting, as when the Specify Requested Exit AST directive is not 
included , 



5.6 PARITY ERROR AST ROUTINE SUPPORT 

Memory parity error AST routine support is most useful to diagnostic 
programmers v;ho v/ant help in locating a malfunctioning memory 
subsystem or module. The Specify Parity Error AST directive is 
provided for this purpose. The specified AST is entered when a task 
that previously issued the Specify Parity .yrror AST directive is 
running, and a parity error occurs. Upon entry to the AST routine, 
the program scack contains 52 bytes of hardv/are-dependent information 
that can be used to identify the physical or functional location of 
the memory subsystem or module causing the error. 



5.7 EXECUTIVE-LEVEL DISPATCHING 

RSX-llM-PLUS provides the user with additional Executive functions. 
These functions provide for the dispatching of multiuser tasks and can 
enhance the interface to slave tasks. 

The dispatching algorithm jsed by the Executive is identical to the 
algorithm used by MCR. Thus, the ability to dispatch copies of 
iiuiltiuser tasks is available at both the MCR command and Executive 
directive level. A consistent scheme for communication and 
synchronization between multiuser tasks is made available at the 
Executive level. 

Uxecutive-lGvel dispatching uses the same naming scheme as is used in 
the MCR dispatching alcjorithin. A single copy of the multiuser task 
must be installed with a name of the form ...mnm. When a task issues 
a directive specifying a task name of the form ...mmm, the Executive 
first forms the task name inmmtnn, where t is the first character of 
the device name of the TI: of the issuing task, and nn is the unit 
number. Trie iixecutive then attempts to perform the directive as if 
the task name mmmtnn has been specified. If the directive is one that 
f;ould activate the task (Request, Spawn, or Send, Request And 
Connect) , a TC3 may be dynamically created and filled in from the 
...mmm TCK. If the directive is a send user-type directive, and the 
TCB mnmtnn does not exist, the send packet is queued to the . . .mmn TCB 
until nmmtnn is activated. At that time any send packets for mmmtnn 
that are queued to the ...mmm TCB are moved to the mmmtnn TCB. 
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This allows for the specification of a specific copy of a multitask in 

a directive whose TI: is different from that of the issuing task. If 

the TI: of the target task is known, the task's name can be, 
calculated and explicitly specified in a directive. 



■^^^T^. 
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CHAPTER 6 
DIRECTIVE DESCRIPTIONS 



Each directive description consists of an explanation of the 
directive's function and use, the names of the corresponding macro and 
FORTRAN calls, the associated parameters, and possible return values 
of the Directive Status Word (DSW) • The descriptions generally show 
the $ form of the macro call (for instance, QIO$) , although the $C and 
$S forms are also available. Where the $S form of a macro requires 
less space and performs as fast as a DIR$ (because of a small DPB) , it 
is recommended. For these macros, the expansion for the $S form is 
shown, rather than that for the $ form. 

In addition to the directive macros themselves, the programmer can use 
the DIR$ macro to execute a directive if the directive has a 
predefined DPB. See Sections 1.4.1.1 and 1.4.2 for further details. 



6.1 DIRECTIVE CATEGORIES 

For ease of reference, the directive descriptions are presented 
alphabetically in Section 6.3 according to the directive macro calls. 
This section, however, groups the directives by function and gives the 
number of the section that describes each directive in detail. The 
directives are grouped into the following nine categories: 

1. Task Execution Control Directives 

2. Task Status Control Directives 

3. Informational Directives 

4. Event-Associated Directives 

5. Trap-Associated Directives 

6. I/O- and Intertask Communications-Related Directives 

7. Memory Management Directives 

8. Parent/Offspring Tasking Directives 

9. R3X-11M-PLUS Directives 

6.1.1 Task Execution Control Directives 

The task execution control directives deal principally with starting 
and stopping tasks. Each of these directives (except Extend Task) 
results in a change of the task's state (unless the task is already in 
the state being requested). These directives are: 
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Macro 


Section 


ABRT$ 


6.3.1 


CSRQ$ 


6.3.14 


EXIT$S 


6.3.26 


EXTK$ 


6.3.28 


RQST$ 


6.3.47 


RSUM$ 


6.3.49 


RUN$ 


6.3.50 


SPND$S 


6.3.57 



Directive Name 

Abort Task 

Cancel Time Based Initiation Requests 

Task Exit ($S form recommended) 

Extend Task 

Request Task 

Resume Task 

Run Task 

Suspend ($S form recommended) 



6.1.2 Task Status Control Directives 

Two task status control directives alter the checkpointable attribute 
of a task. A third directive changes the running priority of an 
active task. These directives are: 



Macro Section Directive Name 

ALTP$ 6.3.2 Alter Priority 

DSCP$S 6.3.17 Disable Checkpointing ($S form recommended) 

ENCP$S 6.3.24 Enable Checkpointing ($S form recommended) 



6.1.3 Informational Directives 



Several directives provide the issuing task with system information 
and parameters such as: The time of day, the task parameters, the 
console switch settings, and partition or region parameters. These 
directives are: 

Directive Name 

Get Partition Parameters 

Get Region Parameters 

Get Sense Switches ($S form recommended) 

Get Time Parameters 

Get Task Parameters 



Macro 


Section 


GPRT$ 


6.3.32 


GREG$ 


6.3.33 


GSSW$S 


6.3.34 


GTIM$ 


6.3.35 


GTSK$ 


6.3.36 



6.1.4 Event-Associated Directives 



The event and event flag directives are the means provided in the 
system for inter- and intra-task synchronization and signaling. These 
directives must be used carefully sincei software faults resulting from 
erroneous signaling and synchroni2;ation are often obscure and 
difficult to isolate. The directives are: 



Macro 


Section 


CLEF$ 


6.3.7 


CMKT$ 


6.3.8 


CRGF$ 


6.3.11 


DECL$S 


6.3.15 


ELGF$ 


6.3.20 


EXIF$ 


6.3.25 


MRKT$ 


6.3.38 


RDAF$ 


6.3.44 


RDXF$ 


6.3.45 



Directive Name 

Clear Event Flag 

Cancel Mark Time Requests 

Create Group Global Event Flags 

Declare Significant Event ($S form recommended) 

Eliminate Group Global Event Flags 

Exit If 

Mark Time 

Read All Event Flags 

Read Extended Event Flags 



fflff^HPft 
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Macr o S ection Directive Nam e 

SETF$ 6,.3.54 Set Event Flag 

WSIG$S 6,.3.76 Wait For Significant Event ($S form recommended) 

WTLO$ 6.,3.77 Wait For Logical OR Of Event Flags 

WTSE$ 6.3.78 Wait For Single Event Flag 



6.1.5 Trap-Associated Directives 

The trap-associated directives provide the user with trap facilities 
that allow transfer of control (software interrupts) to the executing 
tasks. These directives are: 



Macro 


Section 


ASTX$S 


6.3.4 


DSAR$S 


6.3.16 


ENAR$S 


6.3.23 


IHAR$S 


6.3.16 


SFPA$ 


6.3.55 


SPRA$ 


6.3.58 


SRDA$ 


6.3.60 


SRRA$ 


6.3.63 


SVDB$ 


6.3.68 


SVTK$ 


6.7.69 



Directive Nam e 

AST Service Exit ($S form recommended) 
Disable AST Recognition ($S form recommended) 
Enable AST Recognition ($S form recommended) 
Inhibit AST Recognition ($S form recommended) 
Specify Floating Point Processor Exception AST 
Specify Power Recovery AST 
Specify Receive Data AST 
Specify Receive-By-Reference AST 
Specify SST vector Table For Debugging Aid 
Specify SST Vector Table For Task 



6.1.6 I/O- and Intertask Communications-Related Directives 

The I/O- and intertask communications-related directives allow tasks 
to access I/O devices at the driver interface level or interrupt 
level, to communicate with other tasks in the system, and to retrieve 
the MCR command line used to start the task. These directives are: 



Macro 


Section 


ALUN$ 


6.3.3 


CINT$ 


6.3.6 


GLUN$ 


6.3.29 


GMCR$ 


6.3.30 


QIO$ 


6.3.39 


QIOW$ 


6.3.40 


RCVD$ 


6.3.42 


RCVX$ 


6.3.43 


SDAT$ 


6.3.52 



Directive Name 

Assign LUN 

Connect To Interrupt Vector 

Get LUN Information 

Get MCR Command Line 

Queue I/O Request 

Queue I/O Request And Wait 

Receive Data 

Receive Data Or Exit 

Send Data 



6.1.7 Memory Management Directives 

The memory management directives allow a task to manipulate its 
virtual and logical address space, and to set up and control 
dynamically the window-to-region mapping assignments. The directives 
also provide the means by which tasks can share and pass references to 
data and routines. These directives are: 



Macro 



Section 



Directive Name 



ATRG$ 
CRAW$ 



6.3.5 
6.3.10 



Attach Region 

Create Address Window 
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Macro 


Section 


CRRG$ 


6.3.12 


DTRG$ 


6.3.18 


ELAW$ 


6.3.19 


GMCX$ 


6.3.31 


MAP$ 


6.3.37 


RREF$ 


6.3.48 


SREF$ 


6.3.62 


UMAP$ 


6.3.70 



Directive Name 

Create Region 
Detach Region 
Eliminate Address Window 
Get Mapping Context 
Map Address Window 
Receive By Reference 
Send By*Reference 
Unmap Address Window 



6.1.8 Parent/Offspring Tasking Directives 

Parent/offspring tasking directives permit tasks to start other tasks, 
connect to other tasks in order to receive status information, stop 
for terminal I/O, and unstop other tasks. These directives are: 

Directive Name 

Connect 

Exit With Status 

Receive Data Or Stop 

Spawn 

Stop For Logical 'OR' Of Event Flags 

Stop 

Stop For Single Event Flag 

Unstop 



Macro 


Section 


CNCT$ 


6.3.9 


EXST$ 


6.3.27 


RCST$ 


6.3.41 


SPWN$ 


6.3.59 


STLO$ 


6.3.65 


STOP$S 


6.3.66 


STSE$ 


6.3.67 


USTP$ 


6.3.71 



6.1.9 RSX-llM-PLUS Directives 

In addition to the directives just listed) RSX-llM-PLUS includes 
directives that support parent/offspring tasking, virtual terminals, 
CPU'/UNIBUS affinity, Supervisor mode library routines, variable-length 
send/receive data buffers, and parity error and exit AST routine 
support. These directives are: 

Directive Name 

Create Virtual Terminal 
Eliminate virtual Terminal 
Emit Status 

Remove Affinity ($S form only) 
Supervisor Call ($S form only) 
Send, Request And Connect 
Specify Parity Error AST 
Specify Requested Exit AST 
Set Affinity 
Variable Receive Data 
Variable Receive Data Or Stop 
Variable Receive Data Or Exit 
Variable Send Data 



Macro 


Section 


CRVTS 


6.3.13 


ELVT$ 


6.3.21 


EMST$ 


6.3.22 


RMAFSS 


6.3.46 


SCAL$S 


6.3.51 


SDRCS 


6.3.53 


SPEA$ 


6.3.56 


SREA$ 


6.3.61 


STAF$ 


6.3.64 


VRCD$ 


6.3.72 


VRCS$ 


6.3.73 


VRCX$ 


6.3.74 


VSDA$ 


6.3.75 
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6.2 DIRECTIVE CONVENTIONS 

Programmers using system directives should adhere to the following 
conventions: 

1. In MACRO-11 programs, unless a number is followed by a 
decimal point (.), the system assumes the number to be octal. 

In FORTRAN programs, use integer*2 type unless the directive 
description states otherwise. 

2. In MACRO-11 programs, task and partition names can be from 
one to six characters long and should be represented as two 
words in Radix-50 form. 

In FORTRAN programs, specify task and partition names by a 
variable of type REAL (single precision) that contains the 
task or partition name in Radix-50 form. To establish 
Radix-50 representation, either use the DATA statement at 
compile time, or use the IRAD50 subprogram or RAD50 function 
at run time. 

3. Device names are two characters long and are represented by 
one word of ASCII code. 

4. Some directive descriptions state that a certain parameter 
must be provided even though the system ignores it. Such 
parameters are included to maintain RSX-llM compatibility 
with IAS. 

5. In the directive descriptions, square brackets ([ ]) enclose 
optional parameters or arguments. To omit optional items, 
either use an empty (null) field in the parameter list, or 
omit a trailing optional parameter. 

6. Logical Unit Numbers (LUNs) can range from 1 to 255(10). 

7. Event flag numbers range from 1 to 96(10). Numbers from 1 to 
32(10) denote local flags. Numbers from 33 to 64 denote 
common flags. Numbers 65 to 96 denote group-global event 
flags. 

Note that the Executive preserves all task registers when a task 
issues a directive. 



6.3 SYSTEM DIRECTIVE DESCRIPTIONS 

Each directive description includes most o-r all of the following 
elements: 

Name : 

The function of the directive is described. 

FORTRAN Call: 

The FORTRAN subroutine call is shown, and each parameter is 
defined. 
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Macro Call: 

The macro call is shown, each parameter is defined, and the ^^ 
defaults for optional parameters are given in parentheses ' 

following the definition of the parameter. Since zero is 
supplied for most defaulted parameters, only nonzero default 
values are shown. Parameters ignored by RSX-llM are required for 
compatibility with RSX-llD. 

Macro Expansion: " 

The $ form of the macro is expandeid in most of the directive 

descriptions. Where the $S form is recommended for a directive, 

the expansion for that form is shown instead. Expansions for all 

three forms and for the DIR$ macro are illustrated in Section » 

1.4.5. 

Definition Block Parameters:. 

These parameters are given only in the memory management 

directive descriptions. This section describes all the relevant 

input and output parameters in the Region or Window Definition Jt^ 

Block (see Section 3.5). '""'^'^ 

Local Symbol Definitions: 

Macro expansions usually generate local symbol definitions with 
an assigned value equal to the byte offset from the start of the 
DPB to the corresponding DPB element. These symbols are listed. 
The length in bytes of the element pointed to by the symbol 
appears in parentheses following the symbol's description. Thus: 

A.BTTN — Task name (4) .^^ 

defines A.BTTN as pointing to a task name in the Abort Task DPB; 
the task name has a length of 4 bytes. 

DSW Return Code: 

All valid return codes are listed. 

Notes: 

The notes presented with some directive descriptions expand on ^(ttk, 

the function, use, and/or consequences of using the directives. s^^m. 

Users should always read the notes carefully. 
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ABRT$ 



6.3.1 Abort Task 

The Abort Task directive instructs the system to terminate the 
execution of the indicated task. ABRT$ is intended for use as an 
emergency or fault exit. A termination notification is displayed, 
based on the described condition, at one of the following terminals: 

1. The terminal from which the aborted task was requested 

2. The originating terminal of the task that requested the 
aborted task 

3. The operator's console (CO:) if the task was started 
internally from another task via a Run directive, or via an 
MCR Run command that specified one or more time parameters 

A task may abort any task, including itself, when a task is aborted, 
its state changes from active to dormant. Therefore, to reactivate an 
aborted task, a task or an operator must request it. 

In systems that support multiuser protection, a task must be 
privileged to issue the Abort Task directive (unless it is aborting a 
task with the same TI:). 

FORTRAN Call: 

CALL ABORT (tsk[,ids]) 

tsk = Task name 

ids = Directive status 

Macro Call: 

ABRT$ tsk 

tsk = Task name 



Macro Expansion: 

ABRT$ ALPHA 
.BYTE 83. ,3 
.RAD50 /ALPHA/ 



;ABRT$ MACRO DIC, DPB SIZE=3 WORDS 
;TASK "ALPHA" 



Local Symbol Definitions: 

A.BTTN — Task name (4) 
DSW Return Codes: 

IS. sue — Successful completion 

IE. INS — Task not installed 

IE. ACT — Task not active 

lE.PRI — Issuing task is not privileged (multiuser 
protection systems only) 
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lE.ADP — Part of the DPB is out of the issuing task's address 
space 

lE.SDP — Die or DPB size is invalid 

Note : 

When a task is aborted, the Executive frees all the task's 
resources. In particular, the Executive: 

• Detaches all attached devices 

• Flushes the AST queue 

• Flushes the receive and receive-by-reference queue 

• Flushes the clock queue for outstanding Mark Time requests for 
the task 

• Closes all open files (files open for write access are locked) 

• Detaches all attached regions except in the case of a fixed 
task, where no detaching occurs 

• Runs down the task's I/O 

• Frees the task's memory if the aborted task was not fixed 

• Returns a severe error status (EX$SEV) to the parent task when 
a connected task is aborted. 

• Marks virtual terminals created by the aborted task for 
deallocation. The virtual terminals actually become 
deallocated when all tasks using the virtual terminal (s) are 
aborted or exit (see Section 4.2). Nonpr ivileged tasks using 
virtual terminal units that are marked for deallocation as TI : 
are also aborted. 
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ALTP$ 



6.3.2 Alter Priority 

The Alter Priority directive instructs the system to change the 
running priority of a specified active task to either a new priority 
indicated in the directive call, or the task's default (installed) 
priority if the call does not specify a new priority. 

The specified task roust be installed and active. The Executive resets 
the task's priority to its installed priority when the task exits. 

If the directive call omits a task name, the Executive defaults to the 
issuing task. 

The Executive reorders any outstanding I/O requests for the task in 
the I/O queue and reallocates the task's partition. The partition 
reallocation may cause the task to be checkpointed . 

In systems that support multiuser protection, a task must be 
privileged to issue the Alter Priority directive; however, a 
nonprivileged task can lower its priority or raise it to its installed 
priority. 

FORTRAN Call: 

CALL ALTPRI ( [ tsk] , [ ipr i ] [ , ids] ) 

tsk = Active task name 

ipri = 1-word integer value equal to the new priority, a 
number from 1 to 250 (decimal) 

ids = Directive status 

Macro Call: 

ALTP$ [tsk] [,pri] 

tsk = Active task name 

pri == New priority, a number from 1 to 250 (decimal) 

Macro Expansion: 

^LPHA, 75. 

ALTP$ MACRO DIC, DPB SIZE=4 WORDS 
TASK ALPHA 
. NEW PRIORITY 

Local Symbol Definitions: 

A.LTTN — Task name (4) 

A.LTPR — priority (2) 
DSW Return Codes: 

IS. sue — Successful completion 

IE. INS — Task not installed 

IE. ACT — Task not active 
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ALTP$ 


ALPHA, 75. 


.BYTE 


9., 4 


.RAD5 


/ALPHA/ 


.WORD 


75. 
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lE.PRI — Issuing task is not privileged (multiuser protection 
systems only) 

lE.IPR — Invalid priority 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 

lE.SDP — DIG or DPB size is invalid 






iW^'flWli 
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ALUN$ 



6.3.3 Assign LUN 

The Assign LUN directive instructs the system 
device unit to a logical unit number (LUN) . 
the task has attached itself to the device. 



to assign a physical 
It does not indicate that 



The actual physical device assigned 
on the logical assignment table 
RSX-llM/M-PLUS MCR Operations Manual 
the logical assignment table for a 
found, the physical device unit asso 
assigned to the logical unit. 0th 
physical device tables and assigns t 
named to the logical unit. In 
protection, the Executive does not s 
if the task has been installed with 



to the logical unit is dependent 
(see the MCR Assign command in the 
) . The Executive first searches 

device name match. If a match is 
ciated with the matching entry is 
erwise, the Executive searches the 
he actual physical device unit 

systems that support multiuser 
earch the logical assignment table 
the slave option (/SLV=YES) . 



When a task reassigns a LUN from one device to another, the Executive 
cancels all I/O requests for the issuing task in the previous device 
queue. 

FORTRAN Call: 

CALL ASNLUN (lun ,dev ,unt [ , ids] ) 

lun = Logical unit number 

dev = Device name (format: 1A2) 

unt = Device unit number 

ids = Directive status 
Macro Call: 

ALUN$ lun, dev, unt 

lun = Logical unit number 

dev = Device name (two characters) 

unt = Device unit number 



Macro Expansion! 



ALUN$ 


7,TT,0 


.BYTE 


7,4 


.WORD 


7 


.ASCII 


/TT/ 


.WORD 






ASSIGN LOGICAL UNIT NUMBER 
ALUN$ MACRO DIC, DPB SIZE=4 WORDS 
LOGICAL UNIT NUMBER 7 
DEVICE NAME IS TT (TERMINAL) 
DEVICE UNIT NUMBER=0 



Local Symbol Definitions: 

A. LULU — Logical unit number (2) 

A.LUNA — Physical device name (2) 

A.LUNU — Physical device unit number (2) 
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DSW Return Codes: 

IS. sue — Successful completion 

lE.LNL — LUN usage is interlocked (see Note 1 below) 

lE.IDU — Invalid device and/or unit 

IE. ILL! — Invalid logical unit number 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 

lE.SDP — Die or DPB size is invalid 

Notes: 

1. A return code of lE.LNL indicates that the specified LUN 
cannot be assigned as directed. Either the LUN is already 
assigned to a device with a file open for that LUN, or the 
LUN is currently assigned to a device attached to the task, 
and the directive attempted to change the LUN assignment. If 
a task has a LUN assignttd to a device and the task has 
attached the device, the LUN can be reassigned, provided that 
the task has another LUN assigned to the same device. 

2. in RSX-llM-PLUS systems, I/O (output) operations should not 
be executed with spooled devices. 






^P^^HSk 
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ASTX$S 



6.3,4 AST S(!rvice Exit ($S form recommended) 

The AST Service Exit directive instructs the system to terminate 
execution of an AST service routine. 

If another AST is queued and ASTs are not disabled, then the Executive 
immediately effects the next AST. Otherwise, the Executive restores 
the task's pre-AST state. See Notes below. 

FORTRAN Call: 

Neither the FORTRAN language nor the ISA standard permits direct 
linking to system trapping mechanisms; therefore, this directive 
is not available to FORTRAN tasks. 

Macro Call: 

ASTX$S [err] 

err = Error routine address 

Macro Expansion: 



ASTX$S ERR 

MOV (PC)+,-(SP) 

.BYTE 115.,1 

EMT 377 

JSR PC, ERR 



PUSH DPB ONTO THE STACK 

ASTX$S MACRO DIC, DPB SIZE=1 WORD 

TRAP TO THE EXECUTIVE 

CALL ROUTINE "ERR" IF DIRECTIVE 

UNSUCCESSFUL 



Local Symbol Definitions: 

None 
DSW Return Codes: 

IS.SUC — Successful completion 

IE. AST — Directive not issued from an AST service 
routine 



Part of the DPB or stack is out of the issuing task's 
address space 



lE.ADP 

lE.SDP — DIC or DPB size is invalid 



Notes; 



1. A return to the AST service routine occurs if, and only if, 
the directive is rejected. Therefore, no Branch on Carry 
Clear instruction is generated if an error routine address is 
given. (The return occurs only when the Carry bit is set.) 

2. When an AST occurs, the Executive pushes, at minimum, the 
following information onto the task's stack: 

SP+06 — Event flag mask word 

SP+04 — PS of task prior to AST 

SP+02 — PC of task prior to AST 

SP+00 — DSW of task prior to AST 



6-13 



DIRECTIVE DESCRIPTIONS 



The task stack must be in this state when the AST Service Exit 
directive is executed. 

In addition to the data parameters, the Executive pushes 
supplemental Information onto the task stack for certain ASTs. 
For I/O completion, the stack contains the address of the I/O 
status block; for Mark Time, the stack contains the Event 
Flag Number; for a floating-point processor exception, the 
stack contains the exception code and address. 

These AST parameters must be removed from the task's stack 
prior to issuing an AST exit directive. The following example 
shows how to remove AST parameters when a task uses an AST 
routine on I/O completion: 



Example: 



EXAMPLE PROGRAM 
LOCAL DATA 



lOSB: .BLKW 2 
BUFFER: .BLKW 30. 



;I/0 STATUS DOUBLEWORD 
;I/0 BUFFER 



START OF MAIN PROGRAM 



START: 



; PROCESS DATA 



QIOW$C I0.WVB,2,1, ,IOSB,ASTSER,<BUFFER,60.,40> 

; PROCESS & WAIT 
EXIT$S ;EXIT TO EXECUTIVE 



AST SERVICE ROUTINE 



ASTSER: 



; PROCESS AST 



TST 
ASTX$S 



(SP) + 



; REMOVE ADDRESS OF I/O STATUS BLOCK 
;AST EXIT 



The task can alter its return address by manipulating the 
information on its stack prior to executing an AST exit 
directive. For example, to return to task state at an 
address other than the pre-AST address indicated on the 
stack, the task can simply replace the PC word on the stack. 
This procedure may be useful in those cases in which error 
conditions are discovered in the AST routine; but this 
alteration should be exercised with extreme caution since AST 
service routine bugs are difficuTt to isolate. 

Because this directive requires only a 1-word DPS, the $S 
form of the macro is recommended. It requires less space and 
executes with the same speed as the DIR$ macro. 
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ATRG$ 



6.3.5 Attach Region 

The Attach Region directive attaches the issuing task to a static 
common region or to a named dynamic region. (No other type of region 
can be attached to the task by means of this directive.) The Executive 
checks the desired access specified in the region status word against 
the owner UIC and the protection word of the region. If there is no 
protection violation, the desired access is granted. If the region is 
successfully attached to the task, the Executive returns a 16-bit 
region ID (in R.GID) , which the task uses in subsequent mapping 
directives. 
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FORTRAN Calls 

CALL ATRG (irdb[,ids]) 

irdb = An 8-word integer array containing a Region Definition 
Block (see Section 3.5.1.2) 



ids 
Macro Call: 
ATRG$ 
rdb 



= Directive status 



rdb 



Region Definition Block address 



Macro Expansion: 

ATRG$ RDBADR 
.BYTE 57., 2 
.WORD RDBADR 



;ATRG$ MACRO DIG, DPB SIZE=2 WORDS 
;RDB ADDRESS 



Region Definition Block Parameters: 
Input parameters 



Array 
Element 



Offset 



irdb(3)(4) R.GNAM — Name of the region to be attached 

irdb(7) R.GSTS — Bit settingsl in the region status word 

(specifying desired access to the region) : 



1 FORTRAN programmers should refer to Section 3.5.1 to determine the 
bit values represented by the symbolic names described. 
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RS.RED — 1 if read access is desired 

RS.WRT — 1 if write access is desired 

RS.EXT — 1 if extend access is desired 

RS.DEL — 1 if delete access is desired 

Clear all four bits to request the region 
ID of the named region if it is already 
attached to the issuing task. 

Output parameters 

irdb(l) R.GID — ID assigned to the region 

irdb(2) R.GSIZ — Size in 32-word blocks of the attached 

region 

Local Symbol Definition: 

A.TRBA — Region definition block address (2) 
DSW Return Codes: 

IS. sue — Successful completion 

lE.UPN — An attachment descriptor cannot be allocated 

lE.PRI — Privilege violation 

lE.NVR — Invalid region ID 

lE.PNS — Specified region name does not exist 

lE.ADP — Part of the DPB or RDB is out of the issuing task's 
address space 

lE.SDP — Die or DPB size is invalid 

lE.HWR — Region had parity error or load failure 



^^^^flk 
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CINT$ 



6.3.6 Connect To Interrupt Vector 

The Connect To Interrupt Vector directive provides a task with the 
capability of processing hardware interrupts through a specified 
vector. The Interrupt Service Routine (ISR) is included in the task's 
own space. In a mapped system, the issuing task must be privileged. 

The overhead entails the execution of about 10 instructions before 
entry into the ISR, and 10 instructions after exit from the ISR. A 
mechanism is provided for transfer of control from the ISR to 
task-level code, using either an AST or a local event flag. 

After a task has connected to an interrupt vector, it can process 
interrupts on three different levels: interrupt, fork, and task. The 
task level may be subdivided into: AST level and non-AST level. 

1. Interrupt Level 

When an interrupt occurs, control is transferred, via the 
Interrupt Transfer Block (ITB) that has been allocated by the 
CINT$ directive, to the Executive subroutine $INTSC. From 
there control goes to the ISR specified in the directive. 

The ISR processes the interrupt and either dismisses the 
interrupt directly or enters fork level through a call to the 
Executive routine $F0RK2. 

2. Fork Level 

The fork-level routine executes at priority 0, the lowest 
processor priority, allowing interrupts and more 
time-dependent tasks to be serviced promptly. If required, 
the fork routine sets a local event flag for the task and/or 
queues an AST to an AST routine specified in the directive. 

3. Task Level 

At task level, entered as the result of a local event flag or 
an AST, the task does final interrupt processing and has 
access to Executive directives. 

Typically, the ISR does the minimal processing required for an 
interrupt and stores information for the fork routine or task-level 
routine in a ring buffer. The fork routine is entered after a number 
of interrupts have occurred as deemed necessary by the ISR, and 
condenses the information further. Finally, the fork routine wakes up 
the task-level code for ultimate processing that requires access to 
Executive directives. The fork level may, however, be a transient 
stage from ISR to task-level code without doing any processing. 

In a mapped system, a task must be built privileged to be able to use 
the CINT$ directive. However, it is legal to use the /PR:0 switch to 
the Task Builder to have "unprivileged mapping," that is, up to 32K 
words of virtual address space available. This precludes use of the 
Executive subroutines from task-level code; however, the ISR and 
fork-level routines are always mapped to the Executive when they are 
executed. In any case, the Executive symbol table file (RSXllM.STB) 
should be included as input to the Task Builder. 



% m ^- 
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As will be described later, in a mapped system, special considerations 
apply to the mapping of the ISR, fork routine, and enable/disable 
routine as well as all task data buffers accessed by these routines. 

FORTRAN Call: 

Not supported 
Macro Call; 

CINT$ vec,base,isr ,edir ,pri ,ast 

vec = interrupt vector address — Must be in the range 60(8) 
to highest vector specified during SYSGEN, inclusive, 
and must be a multiple of 4. 



base = 



isr 



virtual base address for kernel APR 5 mapping of the 
ISR, and enable/disable interrupt routines — This 
address is automatically truncated to a 32(10)-word 
boundary. The "base" argument is ignored in an 
unmapped system. 

virtual address of the ISR, or to disconnect from 
the interrupt vector 



.ff!^^^^%^ 



edir = 



virtual address 
routine 



of the enable/disable interrupt 



pr 1 



initial priority at which the ISR is to 
execute — This is normally equal to the hard-wired 
interrupt priority, and is expressed in the form n*40, 
where n is a number in the range 0-7. This form puts 
the value in bits 5-7 of pri. It is recommended that 
the programmer make use of the symbols PR4, PR5, PR6, 
and PR7 for this purpose. These are implemented via 
the macro HWDDF$ found in [1,1] EXEMC.MLB. 



ast 



= virtual address of an AST routine to be entered 
the fork-level routine queues an AST 



after 



To disconnect from interrupts on a vector, the argument isr is set 
and the arguments base, edir, psw, and ast are ignored. 

Macro Expansion: 



to 



CINT$ 
.BYTE 
.WORD 
• WORD 
.WORD 

.WORD 

.BYTE 

.WORD 



4 20,BADR,TADR,EDADR,PR5,ASTADR 



,7 



129. 
420 
BADR 
lADR 



EDADR 



PR5,0 



ASTADR 



CINT$ MACRO Die, DPB SIZE = 7 WORDS 

INTERRUPT VECTOR ADDRESS = 420 

VIRTUAL BASE ADDRESS FOR KERNAL APR 

VIRTUAL ADDRESS OF THE INTERRUPT 

SERVICE ROUTINE 

VIRTUAL ADDRESS OF THE INTERRUPT 

ENABLE/DISABLE ROUTINE 

INITIAL INTERRUPT SERVICE ROUTINE 

PRIORITY (LOW BYTE) . (HIGH BYTE = 

VIRTUAL ADDRESS OF AST ROUTINE 



0.) 



Local Symbol Definitions: 

C.INVE — vector address (2) 

C.INBA — base address (2) 

C.INIS — ISR address (2) 



m^ 
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C.INDI — enable/disable interrupt routine address (2) 

C.INPS — priority (1) 

C.INAS — AST address (2) 

DSW Return Codes: 

lE.UPN — An ITB could not be allocated (no pool space) 

IE. ITS — The function requested is "disconnect" and the task 
is not the owner of the vector 

lE.PRI — Issuing task is not privileged (not applicable in 
unmapped system) 

lE.RSU — The specified vector is already in use 

lE.ILV — The specified vector is illegal (lower than 60 or 
higher than highest vector specified during SYSGEN, 
or not a multiple of 4) 

IE. MAP — ISR or enable/disable interrupt routine is not within 
4K words from the value (base address & 177700) 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 

lE.SDP — Die or DPB size is invalid 

Notes: 

1. Checkpointable Tasks 

The following points should be noted for checkpointable tasks 
only: 

V\;hen a task connects to an interrupt vector, checkpointing of 
the task is automatically disabled. 

When a task disconnects from a vector and is not connected to 
any other vector, checkpointing of the task is automatically 
enabled, regardless of its state before the first connect, or 
any change in state while the task was connected. 

2. Mapping Considerations 

In an unmapped system, the argument "base" is ignored, and 
the arguments "isr," "edir," and "ast" require no further 
explanation. 

In a mapped system, however, it must be understood how the 
Executive maps the ISR and enable/disable interrupt routine 
when they are called. The argument "base," after being 
truncated to a 32(10)-word boundary, is the start of a 
4K-word area mapped in kernel APR 5. All code and data in 
the task that is used by the routines must fall within that 
area, or a fatal error will occur, probably resulting in a 
system crash. 

Furthermore, the code and data must be either 
position-independent or coded in such a way that the code can 
execute in APR 5 mapping. When the routines execute, the 
processor is in kernel mode, and the virtual address space 
includes all of the Executive, the pool, and the I/O page. 
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References within the task image must be PC-relative or use a 
special offset defined below. References outside the task 
image must be absolute. 

The following solutions are possible: 

a. Write the ISR, enable/disable interrupt routines, and 
data in position-independent code. 

b. Include the code and data in a common partition, 
task-build it with absolute addresses in APR 5 
{PAR=ISR:120000:20000) , and link the task to the common 
partition. 

c. Build the task privileged with APR 5 mapping and use the 
constant 120000 as argument "base" in the C:[NT$ 
directive. 

d. When accessing locations within the task image in 
immediate or absolute addressing mode, use an offset of 



<120000-<base & 177700>> 



3. ISR 



When the ISR is entered, R5 points to the fork block in the 
Interrupt Transfer Block (ITB) , and R4 is saved and free to 
be used. Registers RO through R3 must be saved and restored 
if used. If one ISR services multiple vectors, the 
interrupting vector can be identified by the vector address, 
which is stored at offset X.VEC in the ITB. The following 
example loads the vector address into R4: 

MOV X.VEC-X.F0RK(R5) ,R4 

The ISR either dismisses the interrupt directly via an RTS PC 
instruction, or calls $F0RK2 if the fork routine is to be 
entered. When calling $F0RK2, R5 must point to the fork 
block in the ITB, and the stack must be in the same state as 
it was upon entry to the ISR. Note that the call must use 
absolute addressing: CALL @#$F0RK2. 

Fork-Level Routine 

The fork-level routine starts immediately after the call to 
$F0RK2. On entry, R4 and R5 are the same as when $F0RK2 was 
called. All registers are free to be used. The first 
instruction of the fork routine must be CLR @R3, which 
declares the fork block free. 

The fork-level routine should be entered if servicing the 
interrupt takes more than 500 microseconds. It must be 
entered if an AST is to be queued or an event flag is to be 
set. (Fork level is discussed in greater detail in the 
RSX-llM Guide to Writing an I/O Driver .) 

An AST is queued by calling the subroutine $QASTC. 

Input: R5 — pointer to fork block in the ITB 

Output: if AST successfully queued — Carry bit = 

if AST was not specified by CINT$ — Carry bit = 1 
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Registers altered: RO, Rl, R2, and R3 

An event flag is set by calling the subroutine $SETF. 

Input: RO — event flag number 

R5 — Task Control Block (TCB) address of task for 
which flag is to be set — This is usually, 
but not necessarily, the task that has 
connected to the vector. This task's TCB 
address is found at offset X.TCB in the ITB. 

Output: specified event flag set 

Registers altered: Rl and R2 

Note that absolute addressing must be used when calling these 
routines (and any other Executive subroutines) from fork 
level : 

CALL @#$QASTC 

CALL @#$SETF 

Enable/Disable Interrupt Routine 

The purpose of the enable/disable interrupt routine, whose 
address is included in the directive call, is to allow the 
user to have a routine automatically called in the following 
three cases: 

a. When the directive is successfully executed to connect to 
an interrupt vector (argument isr nonzero) — The routine 
is called immediately before return to the task. 

b. When the directive is successfully executed to disconnect 
from an interrupt vector (argument isr=0) 

c. When the task is aborted or exits with interrupt vectors 
still connected 

In case a, the routine is called with the Carry bit cleared; 
in cases b and c, with the Carry bit set. In all three 
cases, Rl is a pointer to the Interrupt Transfer Block (ITB). 
Registers RO, R2, and R3 are free to be used; other 
registers must be returned unmodified. Return is 
accomplished by means of an RTS PC instruction. 

Typically, the routine dispatches to one of two routines, 
depending on whether the Carry bit is cleared or set. One 
routine sets interrupt enable and performs any other 
necessary initialization; the other clears interrupt enable 
and cleans up. 

Note that the ITB contains the vector address, in case common 
code is used for multiple vectors. 

AST Routine 

The fork routine may queue as AST for the task through a call 
to the Executive routine $QASTC as described above. When the 
AST routine is entered (at task level) , the top word of the 
stack contains the vector address and must be popped off the 
stack before AST exit (ASTX$S) . 
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7. ITB Structure 

The following offsets are defined relative to the start of 
the ITB: 

X.LNK — link word 

X.JSR — subroutine call to $INTSC 

X.PSW — PSW for ISR (low-order byte) 

X.ISR — ISR address (relocated) 

X.FORK — start of fork block 

X.REL — APR 5 relocation (only in mapped systems) 

X.DSI — address of enable/disable interrupt routine 
(relocated) 

X.TCB — TCB address of owning task 

X.AST — start of AST block 

X.VEC — vector address 

X.VPC — saved PC from vector 

X.LEN — length in bytes of ITB 

The symbols X.LNK through X.TCB are defined locally by the 
macro ITBDF$, which is included in [1 ,1] EXEMC.MLB . All 
symbols are defined globally by [1,1] EXELIB.OLB. 

The following programming example illustrates the use of the CINT$ 
directive : 



+ + 



•TITLE PUNTSK PUNCH ASCII TEXT ON PAPER TAPE PUNCH 

THIS TASK WILL PUNCH AN ASCII STRING TO THE PAPER TAPE PUNCH 
USING THE CINT$ DIRECTIVE. 

IT MUST BE BUILT USING THE /PR : TASK BUILDER SWITCH. JIHN 

NOTE THAT THIS METHOD ALLOWS A TASK TO BE A FULL 32K '' 

WORDS LONG. IF IT IS NECESSARY TO ACCESS THE I/O PAGE 
IN OTHER THAN THE ENABLE/DISABLE ROUTINE OR THE ISR 
THE TASK MUST BE LINKED TO A COMMON BLOCK COVERING 
THE CORRECT PART OF THE I/O PAGE. 

TASK BUILD COMMAND FILE: 

PUNTSK/MM/PR:0/-FP,PUNTSK/-SP/MA=PUNTSK 
[1,54]RSX11M.STB/SS 
/ 

GBLDEF=$VECTR:74 
GBLDEF=$DVCSR: 177554 
UNITS=1 
ASG=TI:1 
PAR=GEN:0:40000 

IT IS POSSIBLE TO HAVE THIS TASK TYPE ON THE CONSOLE TERMINAL ^^^i 

IF THERE IS NO PAPER TAPE PUNCH AVAILABLE. TO DO THIS THE 
VECTOR FOR THE CONSOLE OUTPUT MUST APPEAR TO BE UNUSED. THIS 
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MAY BE DONE BY (ON A TERMINAL OTHER THAN THE CONSOLE!) OPENING 
THE VECTOR LOCATION (64) AND REPLACING ITS CONTENTS WITH 
THE VALUE OF '$NSO' AS OBTAINED FROM A MAP OF THE SYSTEM. BE 
SURE TO REMEMBER THE OLD VALUE OR YOUR CONSOLE WILL BE DEAD 
UNTIL YOU REBOOT THE SYSTEM. NOW TASK BUILD USING THE FOLLOWING 
COMMAND FILE: 

PUNTTY/MM/PR s ,/-FP , PUNTTY/-SP/MA=PUNTSK 
[1,54]RSX11M.STB/SS 
/ 

GBLDEF=$VECTR:64 
GBLDEF=$DVCSR: 177564 
UNITS=1 
ASG=TI:1 
PAR=GEN: 0:40000 



NOTE THAT IN THE ABOVE TWO TKB COMMAND FILES THE FOLLOWING 
CHANGES MUST BE MADE IN ORDER TO RUN ON AN UNMAPPED SYSTEM: 

1) /MM SHOULD BE CHANGED TO /-MM 

2) 'PAR=GEN:0:40000' SHOULD BE CHANGED TO 

•PAROGEN: 40000: 40000' 

IN ADDITION, PLACE A SEMI-COLON IN FRONT OF THE SOURCE LINE 
BELOW THAT DEFINE THE SYMBOL 'M$$MGE'. 

MCALL CINT$, QIOW$, CLEF$S, WTSE$S, EXIT$S, DIR$ 

LOCAL SYMBOLS 



LUN FOR TERMINAL I/O 

EFN FOR TERMINAL I/O 

EFN TO WAIT FOR PUNCHING TO COMPLETE 

DEFINE THIS SYMBOL TO RUN ON MAPPED SYSTEM 



LUN.TT = 1 

EFN.TT = 1 

EFN.WF = 2 

M$$MGE = 
+ + 

MACRO TO GENERATE AN ASCII STRING AND A QIO TO OUTPUT 

THE STRING TO THE TERMINAL. 

MESSG NAM, STRING 

WHERE: 

NAM IS THE NAME OF THE GENERATED QIO DPB 
STRING IS THE ASCII STRING TO OUTPUT 



LBL: 
NAM: 



.MACRO MESSG NAM, STRING ,?LBL 

$CHR=0 

.IRPC X,<STRING> 

$CHR=$CHR+1 

ENDR 

.ENABL LSB 

.ASCII /STRING/ 

. EVEN 

QIOW$ 10. WVB, LUN.TT, EFN.TT,, , , <LBL , $CHR , 40> 

.DSABL LSB 

.ENDM 



MESSG HELLO, <CONNECT TO INTERRUPT TEST> 

MESSG CINWRK,<CONNECT TO INTERRUPT WORKS — CHECK THE PAPER TAPE 
PUNCH> 



CINT: CINT$ $VECTR , $BASE , $PNISR, $PNEDI ,PR4 
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/CONNECT TO INTERRUPT 
; VECTOR=$VECTR 

BASE . FOR . MAPPING=$BASE 

ISR=$PNISR 

ENB . DSABL . RTN=$PNEDI 

PRI0=PR4 



DISCON:CINT$ $VECTR,0,0 



/DISCONNECT FROM INTERRUPT 
; VECTOR=74 



++ 



ENTRY POINT TO THE PUNCH TASK. THE TASK WILL ANNOUNCE 

ITSELF ON THE INITIATING TERMINAL,, CONNECT TO THE 

SPECIFIED VECTOR, OUTPUT THE ASCII STRING, AND THEN 

OUTPUT A MESSAGE THAT IT WAS SUCCESSFUL. IF THE TASK 
TERMINATES WITH AN I/O TRAP THE CONNECT-TO-INTERRUPT 

DIRECTIVE FAILED, AND Rl WILL CONTAIN THE DSW RETURNED 

IN ORDER TO DIAGNOSE THE ERROR. 



$PUNTK: :DIR$ 
DIR$ 



BC$ 

WTSE$S 

DIR$ 

DIR$ 

EXIT$S 



ERRl: 



$BASE; 



MOV 
MOV 
lOT 



#HELLO 
#CINT 



ERRl 
#EFN.WF 
#DISCON 
#CINWRK 



#1,R0 
$DSW,R1 



ANNOUNCE THAT WE ARE HERE 

CONNECT TO THE PUNCH 

THIS CAN BE EITHER THE TERMINAL 
OR THE PAPER TAPE PUNCH. 

IF CS THEN DIRECTIVE ERROR 

WAIT FOR PUNCH TO FINISH 

DISCONNECT FROM INTERRUPTS 

TELL USER THAT CINT WORKS 



ERROR # 1 

GET THE DSW TO SHOW THE CINT ERROR RETURN 

DUMP REGISTERS 

THIS IS THE BASE OF THE MAPPING USED 
BY THE EXECUTIVE WHEN MAPPING TO THE 
'DRIVER'. THIS MAPPING IS REQUIRED 
ONLY ON MAPPED SYSTEMS; UNMAPPED 
SYSTEMS DO NOT HAVE THIS PROBLEM. 



*IP^^^ 



+ + 



PUNMSG i 



FOLLOWING IS THE ASCII STRING PUNCHED BY THIS TASK, 



.NLIST BEX 

.ASCIZ /ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 !§#$%'"&*() +-=/<15><12> 

.LIST BEX 

.EVEN 

POINTER INTO PUNMSG FOR ISR 
TCB ADDRESS OF TASK 
PAPER TAPE PUNCH CSR ADDRESS 
PAPER TAPE PUNCH BUFFER ADDRESS 



THIS ROUTINE IS CALLED BY THE EXEC ON EITHER A CONNECT OR DISCONNECT 
FROM INTERRUPT VECTOR REQUEST, OR WHEN THE TASK EXITS WITH INTERRUPT 
VECTORS STILL CONNECTED. 

ENTRY CONDITIONS: 



PUNPTR: 


.WORD 





TSKTCB : 


.WORD 





PUNCSR: 


.WORD 


$DVCSR 


PUNBUF: 


.WORD 


$DVCSR+2 


;++ 






; ENABLE/DISABLE ROUTINE 



C-CLEAR 
C-SET 

$TKTCB 



THIS IS A SUCCESSFUL CONNECT. 
THIS IS A DISCONNECT. 

THE TCB ADDRESS OF THE CURRENTLY EXECUTING TASK (MEM) . 
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ACTION: 

IF THE C-BIT IS SET WE MERELY DISABLE THE PUNCH AND RETURN. IF 
THE C-BIT IS CLEAR WE WILL ENABLE THE PUNCH TO INTERRUPT. THIS 
WILL IMMEDIATELY CAUSE AN INTERRUPT AND THE INTERRUPT SERVICE 
ROUTINE WILL OUTPUT CHARACTERS TO THE PUNCH (ONE PER 
INTERRUPT) UNTIL A ZERO BYTE IS OUTPUT. THE ISR WILL THEN FORK 
AND SET THE LOCAL EVENT FLAG 'EFN.WF'. THIS WILL THEN CAUSE THE 
TASK PORTION OF THIS TASK TO CONTINUE EXECUTING AND EVENTUALLY 
EXIT. 



$PNEDI: :BCS 
MOV 



20$ ;IF CS THEN DISCONNECT 

@#$TKTCB,TSKTCB ; COPY TASK TCB ADDRESS FOR LATER 
;S0 WE CAN SET EFN . 



.IF DF M$$MGE 
MOV 



; MAPPED SYSTEM? 



20$; 



.IFF 

MOV 

• ENDC 

BIS 
RETURN 



BIC 
RETURN 



#PUNMSG+120000-<$BASE&177700>,PUNPTR /RELOCATE ADDRESS 
;T0 APR 5 MAPPING, AND SET UP 
; BUFFER POINTER 

M$$MGE ; UNMAPPED SYSTEM? 

#PUNMSG,PUNPTR ;SET UP BUFFER POINTER 



#100,@PUNCSR ;ALLOW INTERRUPTS 

;WHEN WE ARE DONE PUNCHING 
#100,@PUNCSR ;DISABLE INTERRUPTS 



.END 
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6.3.7 Clear Event Flag 

The Clear Event Flag directive instructs the system to report an 
indicated event flag's polarity and then clear it. 

FORTRAN Call: 

CALL CLREF (efn[,ids]) 

efn = Event flag number 

ids = Directive status 

Macro Call: 

CLEF$ efn 

efn = Event flag number 

Macro Expansion: 

CLEF$ 52. 

.BYTE 31., 2 ;CLEF$ MACRO DIC, DPB SIZE=2 WORDS 

.WORD 52. ; EVENT FLAG NUMBER 52. 

Local Symbol Definitions: 

C.LEEF — Event flag number (2) 
DSW Return Codes: I - 

IS.CLR — Successful completion; flag was already clear 

IS. SET — Successful completion; flag was set 

lE.IEF — Invalid event flag number (EFN>64 or EFN<1) 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 

lE.SDP — DIC or DPB size is invalid 
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6.3.8 Cancel Mark Time Requests 

The Cancel Mark Time Requests directive instructs the system to cancel 
a specific Mark Time Request or all Mark Timfe requests that have been 
made by the issuing task. 

FORTRAN Calls 

CALL CANMT ( [ef n ,ast] [ , ids] ) 

ids == Directive status 

efn == Event flag number 

ast == Mark time AST address 
Macro Call: 

CMKT$S [efn, ast, err] 

err == Error routine address 

efn == Event flag number 

ast = Mark time AST address 
Macro Expansion: 

NOTE: THERE ARE TWO IGNORED ARGUMENTS 

PUSH DPB ONTO THE STACK 

CMKT$ MACRO DIC, DPB SIZE=3 WORDS 

EVENT FLAG NUMBER 52. 

ADDRESS OF MARK TIME REQUEST AST ROUTINE 

TRAP TO THE EXECUTIVE 

BRANCH IF DIRECTIVE SUCCESSFUL 

OTHERWISE, CALL ROUTINE "ERR" 



CMKT$ 


52. ,MRKAST,ERR 


MOV 


(PC)+,-(SP) 


.BYTE 


27. ,3 


.WORD 


52. 


.WORD 


MRKAST 


EMT 


377 


BCC 


.+6 


JSR 


PC, ERR 



NOTE 

The above example will cancel only the 
request specified by the ast parameter. 
If all requests are to be canceled, no 
ast or efn parameters will be specified, 
and the DPB size will equal 1. 



Local Symbol Definitions: 

C.MKEF — Event flag number (2) 

C.MKAE — Mark Time Request AST routine address (2) 
DSW Return Codes: 

IS. sue — Successful completion 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 

lE.SDP — DIC or DPB size is invalid 
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Notes: 



1. If neither the efn nor ast parameters are specified, all Mark 
Time Requests issued by the task are canceled. In addition, 
the DPB size will be 1 word. (When either the efn and/or ast 
parameters are specified, the DPB size will be 3 words.) 

2. If both efn and ast parameters are specified (and non-zero) , 
only Mark Time Requests issued by the task specifying either 
that event flag or AST address are canceled. 

3. If only one efn or ast parameter is specified (and non-zero), 
only Mark Time Requests issued by the task specifying the 
event flag or AST address are canceled. 



i^'^'flflv 
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CNCT$ 



6.3.9 Connect 

The Connect directive synchronizes the task issuing the directive with 
the exit or emit status of another task (offspring) that is already 
active. An Offspring Control Block (OCB) is queued to the offspring 
task, and the issuing task's rundown count (contained in the issuing 
task's Task Control Block) is incremented. The rundown count is 
maintained to indicate the combined total number of tasks presently 
connected as offspring tasks and the total number of virtual terminals 
the task has created." The exit AST routine is called when the 
offspring exits or emits status, with the address of the associated 
exit status block on the stack. This directive should not be issued 
to connect to Command Line Interpreter (CLI) tasks; it is illegal to 
connect to a CLI task. 

FORTRAN Call: 

CALL CNCT (rtname, [iefn] , [iast] , [iesb] , [iparm] , [ids] ) 

rtnarae = Name of the offspring task to be connected 

iefn = Event flag to be set when the offspring task exits 
or- emits status 

iast = Address of an AST routine to be called when the 
offspring task exits oif emits status 

iesb = Address of an 8-word status block to be written when 
the offspring task exits Or emits status 

word — Offspring task exit status 

word 1-7 — Reserved 

iparm = Address of a word to receive the status block 
address when an AST occurs 

ids = Integer to receive the Directive Status Word 

Macro Call: 

CNCT$ tname, [efn] , [east] , [esb] 

tname = Name of the offspring task to be connected 

efn = The event flag to be cleared on issuance and set 
when the offspring task exits or emits status 

east = Address of an AST routine to be called when the 
offspring task exits or emits status 

esb = Address of an 8-word status block to be written when 
the offspring task exits ':tgC WIS-' :ii^SW' 

word — Offspring task exit status 
word 1-7 — Reserved 
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ALPHA, 


• BYTE 


143. ,6 


.RAD50 


ALPHA 


.WORD 


1 


.WORD 


CONAST 


.WORD 


STBUF 
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Macro Expansion: 

TBUF Jlik 

CNCT$ MACRO DIC, DPB SIZE=6 WORDS I 

OFFSPRING TASK NAME 

EVENT FLAG NO = 1 

AST ROUTINE ADDRESS 

EXIT STATUS BLOCK ADDRESS 

Local Symbol Definitions: 

C.NCTN — Task name (4) 

C.NCEF — Event flag (2) 

C.NCEA — AST routine address (2) 

C.NCES — Exit status block address (2) 
DSW Return Codes: 

IS. sue — Successful completion 



^ff^^^^ife 



lE.UPN — Insufficient dynamic memory to allocate an offspring 
control block 

IE. INS — The specified task was a command line interpreter 

IE. ACT — The specified task was not active 

lE.IEF — An invalid event flag number was specified 

lE.ADP — Part of the DPB or exit status block is not in the 
issuing task's address space 

lE.SDP — DIC or DPB size is invalid 
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6.3.10 Create Address Window 

The Create Address Window directive creates a new virtual address 
window by allocating a window block from the header of the issuing 
task and establishing its virtual address base and size. (Space for 
the window block has to be reserved at task-build time by means of the 
WNDWS keyword. See the RSX-llM/M-PLUS Task Builder Manual. ) Any 
existing windows that overlap the specified range of virtual addresses 
are unmapped and then eliminated. If the window is successfully 
created, the Executive returns an 8-bit window ID to the task. 

The 8-bit window ID returned to the task is a number from 1 to 15, 
which is an index to the window block in the task's header. The 
window block describes the created address window. 

If WS.SIS in the window status word is set, the Executive creates the 
window in Supervisor mode I-space. Program control can subsequently 
be transferred to Supervisor mode I-space upon issuing a Supervisor 
Call directive. 

If WS.MAP in the *?indow status word is set, the Executive proceeds to 
map the window according to the Window Definition Block input 
parameters. 



A task can specify any length for the mapping assignment that is less 
than or equal to both the window size specified when the window was 
created, and the length remaining between the specified offset within 
the region and the end of the region. 

If W.NLEN is set to 0, the length defaults to either the window size 
or the length remaining in the region, whichever is smaller. (Because 
the Executive returns the actual length mapped as an output parameter, 
the task must clear that offset before issuing the directive each time 
it wants to default the length of the map.) 

The values that can be assigned to W.NOFF depend on the setting of bit 
WS.64B in the window status word (W.NSTS) : 

• If WS.64B = 0, the offset specified in W.NOFF must represent a 
multiple of 256 words (512 bytes). Because the value of 
W.NOFF is expressed in units of 32-word blocks, the value must 
be a multiple of 8. 

• If WS.64B = 1, the task can align on 32-word boundaries; the 
programmer can therefore specify any offset within the region. 

NOTE 

Applications dependent on 32-word or 
64-byte alignment (WS.64B = 1) may not 
be compatible with future software 
products. To avoid future 
incompatibility, programmers should 
write applications adaptable to either 
alignment requirement. The bit setting 
of WS.64B could be a parameter chosen at 
assembly time (by means of a prefix 
file), at task-build time (as input to 
the GBLDEF option) , or at run time (by 
means of command input) . 
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FORTRAN Call: 

CALL CRAW (iwdb[,ids]) ^^%: 

iwdb = An 8-word integer array containing a window definition 
block (see Section 3.5.2.2) 

ids = Directive status 
Macro Call: 

CRAW$ wdb 

wdb = Window Definition Block address 

Macro Expansion: 

CRAW$ WDBADR 

.BYTE 117., 2 ;CRAW$ MACRO DIG, DPS SIZE=2 WORDS 

.WORD WDBADR ; WDB ADDRESS 



Window Definition Block Parameters: 

Input parameters 

Array 

Element Offset 

iwdb(l), W.NAPR — Base APR of the address window to be 
bits 8-15 created 

iwdb(3) W.NSIZ — Desired size, in 32-word blocks, of the 

address window 

iwdb(4) W.NRID — ID of the region to which the new window 

is to be mapped, or for task region (to 
be specified only if WS.MAP=1) 

iwdb(5) W.NOFF — Offset in 32-word blocks from the start 

of the region at which the window is to 
start mapping (to be specified only if 
WS.MAP=1). Note that if WS.64B in the 
window status word equals 0, the value 
specified must be a multiple of 8. 

iwdb(6) W.NLEN — Length in 32-word blocks to be mapped, or 

if the length is to default to either 
the size of the window or the space 
remaining in the region, whichever is 
smaller (to be specified only if 
WS.MAP=1) 

iwdb(7) W.NSTS — Bit settingsl in the window status word: 

WS.MAP — 1 if the new window is to be 
mapped 

WS.WRT — 1 if the mapping assignment 
is to occur with write access 

WS.64B — for 256-word (512-byte) 
alignment, or 1 for 32-word 
(64-byte) alignment 
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Output parameters 

iwdb(l), W.NID — ID assigned to the window 
bits 0-7 

iwdb(2) W.NBAS — virtual address base of the new window 

iwdb(6) W.NLEN — Length, in 32-word blocks, actually 

mapped by the window 

iwdb(7) W.NSTS — Bit settingsl in the window status word: 

Bit Definition (if bit=l) 

WS.CRW — Address window was 

successfully created 

WS.UNM — At least one window was 
unmapped 

WS.ELW — At least one window was 
eliminated 

WS.RRF — Reference was successfully 
received 

WS.NBP — Do not bypass the cache (for 
multiprocessor systems) 

WS.RES — Map only if resident 

WS.NAT — Create attachment descriptor 
only if necessary (for Send 
By Reference directives) 



WS.64B — Define the task's permitted 
alignment boundaries — 
for 256-word {512-byte) 
alignment, 1 for 32-word 
(64-byte) alignment 

WS.MAP — Window is to be mapped 

WS.RCX — Exit if no references to 
receive 



WS.SIS — Create window in Supervisor 
I-space 

WS.BPS — Always bypass the cache for 
this window (for 
multiprocessor systems) 

WS.DEL — Send with delete access 

WS.EXT — Send with extend access 



1 FORTRAN programmers should refer to Section 3.5.2 to determine the 
bit values represented by the symbolic names described. 
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WS.WRT --• Send with write access or map 
with write access 

WS.RED — Send with read access 

Local Symbol Definitions: 

C.RABA — Window definition block address (2) 
DSW Return Codes: 

IS. sue — Successful completion 

lE.HWR — Directive failed in mapping storage because region 
has incurred a parity error 

lE.PRI — Requested access denied at mapping stage 

lE.NVR — Invalid region ID 

lE.ALG — Task specified either an invalid base APR and window 
size combination, or an invalid region offset and 
length combination in the mapping assignment; or 
WS.64B = and the value of W.NOFF is not a multiple 
of 8 

lE.WOV — No window blocks available in task's header 

lE.ADP — Part of the DPB or WDB is out of the issuing task's 
address space 

lE.SDP — Die or DPB size is invalid 
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CRGF$ 



6.3.11 Create Group Global Event Flags 

The Create Group Global Event Flags directive creates a Group Global 
Event Flag Control Block (GFB) and links it into the GFB list. If a 
GFB for the specified group is not present when the directive is 
issued, the Executive creates the GFB data structure with all event 
flags initialized to zero. If a GFB is present when the directive is 
issued, the present GFB is used and the event flags are not 
initialized. However, if the GFB is marked for delete (by a 
previously issued Eliminate Group Global Event Flags directive), the 
Executive clears the GS.DEL bit (see Section 6.3.20). 

FORTRAN CALL: 

CALL CRGF ( [group] ,[ idsw] ) 

group = Group number for the flags to be created. Only 
privileged tasks can specify group numbers other than 
the issuing task's group UIC. If not specified, the 
task's protection UIC (H.CUIC+1) in the task's header 
is used. 

•idsw = Integer to receive the Directive Status Word 

Macro Call: 

CRGF$ group 

group = Group number for the flags to be created. Only 
privileged tasks can specify group numbers other than 
the issuing task's group UIC. If not specified, the 
task's protection UIC (H.CUIC+1) in the task's header 
is used. 

Macro Expansion: 

CRGF$ 4 

.BYTE 157., 2 ;CRGF$ MACRO DIC, DPB SIZE=2 WORDS 

.WORD 4 ;GROUP 4 GLOBAL EVENT FLAGS 

Local Symbol Definitions: 

C.RGRP — Group Number (2) 
DSW Return Codes: 

IS. sue — Successful completion 

lE.UPN — Insufficient dynamic storage 

lE.PRI — Privilege violation 

lE.IUI — Invalid group 

lE.RSU — Event flags already exist 

lE.APD — Part of the DPB is out of the issuing task's address 
space 

IE. DIC — DIC or DPB size is invalid 
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6.3.12 Create Region 

The Create Region directive creates a dynamic region in a 
system-controlled partition and optionally attaches it to the issuing 
task. 

If RS.ATT is set in the region status word, the Executive attempts to 

attach the task to the newly created region. If no region name has 

been specified, the user must set RS.ATT (see the description of the 
Attach Region directive) . 

By default, the Executive automatically marks a dynamically created 
region for deletion when the last task detaches from it. To override 
this default condition, the user can set RS.NDL in the region status 
word as an input parameter. Note that programmers should be careful 
in considering overriding the delete-on-last-detach option. An error 
within a program can cause the system to lock by leaving no free space 
in a system-controlled partition. 

If the region is not given a name, the Executive ignores the state of 
RS.NDL. All unnamed regions are deleted when the last task detaches 
from them. 

Naned regions in RSk-llM-PLUS systems are put ; In the Common Block 
Directory (CBb) . However, memory is not allocated until the Executive 
maps a task to the region. 

The Executive returns an error if there is not enough space to 
accommodate the region in the specified partition. See Notes below. 

FORTRAN Call: 

CALL CRRG (irdb[,ids]) 

irdb = An 8-word integer array containing a Region Definition 
Block (see Section 3.5.1.2) 

ids = Directive status 
Macro Call: 

CRRG$ rdb 

rdb = Region Definition Block address 

Macro Expansion: 

CRRG$ RDBADR 

.BYTE 55., 2 ;CRRG$ MACRO DIC, DPB SIZE = 2 WORDS 

.WORD RDBADR ; RDB ADDRESS 

Region Definition Block Parameters: 

Input parameters 

Array 

Element Offset 

irdb(2) R.GSIZ — Size, in 32-word blocks, of the region 

to be created 
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irdb(3)(4) R.GNAM — Name of the region to be created, or 

for no name 

irdb(5) (6) R.GPAR — Name of the system-controlled partition 

in which the region is to be allocated, 
or for the partition in which the task 
is running 

irdb(7) R.GSTS — Bit settings^ in the region status word: 

Bit Definition (if bit=l) 

RS.CRR — Region was successfully 
created 

RS.UNM — At least one window was 
unmapped on a detach 

RS.MDL — Mark region for deletion on 
last detach 

RS.NDL — The region should not be 
deleted on last detach 

RS.ATT — Created region should be 
attached 

RS.NEX — Created region is not 
extendible 

RS.RED — Read access is desired on 
attach 

RS.WRT — Write access is desired on 
attach 

RS.EXT — Extend access is desired on 
attach 

RS.DEL — Delete access is desired on 
attach 

irdb(8) R.GPRO — Protection word for the region 

( DEWR , DEWR , DEWR , DEWR ) 

Output parameters 

irdb(l) R.GID — ID assigned to the created region 

(returned if RS.ATT=1) 

irdb(2) R.GSIZ — Size in 32-word blocks of the attached 

region (returned if RS.ATT=1) 

irdb(7) R.GSTS — Bit settingsl in region status word: 

RS.CRR — 1 if region was successfully 
created 



1 FORTRAN programmers should refer to Section 3.5.1 to define the bit 
values represented by the symbolic names described. 
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Local Symbol Definitions: 

C.RRBA — Region Definition Block address (2) ^^^\. 

DSW Return Codes: 

IS. sue — Successful completion 

lE.UPN — A Partition Control Block (PCB) or an attachment 
descriptor could not be allocated, or the partition 
was not large enough to accommodate the region, or 
there is currently not enough continuous space in the 
partition to accommodate the region 

lE.HWR — The directive failed in the attachment stage because *" 

a region parity error was detected 

lE.PRI — Attach failed because desired access was not allowed 

lE.PNS — Specified partition in which the region was to be 
allocated does not exist; or no region name was 
specified and RS.ATT = idillH 

lE.ADP — Part of the DPB or RDB is out of issuing task's 
address space 

lE.SDP — Die or RDB size is invalid 

Notes: 

1. The Executive does not return an error if the named region 
already exists. In this case, the Executive clears the 

RS.CRR bit in the status word R.GSTS. If RS.ATT has been 0K^ 
set, the Executive attempts to attach the already existing 
named region to the issuing task. 

2. The protection word (see R.GPRO above) has the same format as 
that of the file system protection word. There are four 
categories, and the access for each category is coded into 
four bits. From low order to high order, the categories 
follow this order: system, owner, group, world. The access 
code bits within each category are arranged (from low order 
to high order) as follows: read, write, extend, delete. A 

bit that is set indicates that the corresponding access is .JW|k, 
denied . 

The issuing task's UIC is the created region's owner UIC. 

In order to prevent the creation of common blocks that are 
not easily deleted, the system and owner categories are 
always forced to have delete access, regardless of the value 
actually specified in the protection word. ^ 
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6.3.13 Create Virtual Terminal 

The Create Virtual Terminal directive creates the data structure tor a 
virtual terminal unit Device Control Block (DCB) and Unit Control 
Block (UCB) and links it into the device list assigning it the lowest 
available virtual terminal unit number. Only a single copy of the 
Status Control Block (SCB) is required. The data structure for 
Virtual Terminal Unit (VTO:) is used as a template for these 
dynamically created data structures. Therefore, VTO: is never 
assigned as a virtual terminal unit number. 

On successful completion of this directive, the assigned VT: unit 
number is returned in the DSW with ttie Carry bit clear. The task must 
save this number if this virtual terminal is to be referenced in 
another directive. 

A rundown count is maintained in the issuing task's TCB to indicate 
the total (current) number of virtual terminals the task has created 
and the number of connected offspring tasks. This count is reduced 
when an Eliminate Virtual Terminal directive is issued specifying this 
VT : unit. 

The input and output AST routines for the virtual terminal unit are 
entered with the following three words on the stack: 

SP+04 — third parameter word (VFC) of offspring request 
Sl' + 02 — byte count of offspring request 

SP+00 — virtual corminal unit number (low byto) I/O 
subfunction code of offspring request (high byte) 

The attacli and detach AST routines arc entered with the following 
three words on the stack; 

SP+04 — second word of offspring task name (0 if detach AST) 
SP+02 -- first word of offspring task name (0 if detach AST) 
SP + 00 — v::rtual terminal unit number (low byte) I/O 
subfunction code of offspring request (high byte) 

Note that the detach AST routine is entered with in both task name 
words on the stack. The AST routine must remove the three words from 
the stack before it issues an AST Service Flxit directive. 

Parent tasks can service each offspring input or output request with a 
corresponding output or input request to the correct virtual device 
unit. For example, where Macro-11 has been activated as an offspring 
task of the Batch processor with a TI : of VT3: 

1. Macro-11 issues an IO.r«VB or lO.RLB to TI : for its first 
input line. The virtual terminal driver queues the read 
request internally and effects an AST in the Batch Processor 
at the virtual address "iast" with the unit number 3 and the 
byte count from Macro-11's I/O request on the stack. 

2. In its AST routine, the Batch Processor retrieves an input 
lire for Macro-11 from the Batch stream, and specifies this 
line in a QIO directive to a LUN" assigned to VT3 : with an 

::o.wvB or io.v>/LB. 

3. The virtual terminal driver reads the lino from the Batch 
Processor's buffer, writes the line to Hacro-11's buffer and 
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then; signals I/O completion for both I/O requests. 
Similarly^ if Macro-11 needs to print an error message, it 
does so with an lO.WVB or lO.WLB to TI : . j«% 

4. ;ln its output AST routine, the Batqh Processor issues an 

\ lO.RVB or 10. RLE to retrieve the Line via the virtual ' 

M;erminal driver. The Batch Processor may then output this 

line to its log file. The third Word on the AST stack in the 

^ Batch output AST routine Is the vertical format character, 

telling Batch what type of carriage; control is expected for 

the output line. This word v/ould be ignored in the input AST 

■ . routine. ■ 

The virtual terminal driver does not interpret or modify transferred 

bytes, I/O subfunction codes, or vertical format characters. However, 

this driver does automatically truncate offspring I/O requests to the 

maximum byte count specified in the "mien" parameter notifying neither 

the parent nor offspring task. The actual number of bytes transferred 

on : each request is equal to the smaller of the byte counts specified 

in the offspring and parent l/o requests. The total number of bytes 

transferred: : is returned in the correspondinei I/O status blocks. Note 

tha:t;: offspring tasks can receive "mien" in the fourth characteristics ,,m 

word when a Get LUN Information directive is issued. ' '','S 

Intermediate buffering in the Executive pool > when enabled by the 

pareint ta^k, is performed on offspring input and output requests when 

the :offspring task is checkpointable, is not at AST state, and is not 

already stopped. ■ Offspring tasks, therefore, may be stopped and 

checkpointedV If the parent task is stopped: and checkpointed at the 

time of the issuance of an I/O request by the of fspr ing , the resulting 

AST brings the parent task to an unstopped state from which it may 

return tbjnemory to service the I/O request. Upon exit from the AST 

routine the parent task is again stopped. : This mode of operation ^^ 

allows the parent and offspring tasks to share the same physical 

memory, even while the parent task services the terminal I/O requests 

for- the off ispr ing task. Whenever, for any reason, the virtual 

terminal driver determines that is should not use intermediate 

buffering, offspring tasks are locked in memory when I/O requests are 

issued, and transfers occur directly between/parent and offspring 

buf fers.--; ■■ 

The intermediate buffering of offspring I/O requests can normally be 

enabled and disabled by the parent task::via the lO.STC function as 

described below. An exception to this exists -^for virtual terminals ^^^ 

created : with a "mien" parameter greater: than a system-wide maximum / ;^ 

specified at Sysgen time, (Sysgen does not allow this maximum to be 

greater than 512.) If a Create virtual Terminal directive is specified 

with a "mien" parameter greater than the system-wide maximum, the 

parameter: is accepted, but Intermediate buffering for the created 

yirttiai; termirial unit is automatically disabled. Furthermore, 

intermediate: buffering for that unit cannot be enabled by the parent 

yia the lO.STC function. 

■parent tasks specify the first word of the I/O completion status for 
the ^offspring request in the third parameter word of the QIO DPB . For 
eix^mpie, an offspring input request may be honored with a write 

/logical of 10 characters with IS. OR in the third parameter word. If 
the :0£fspring request was for 10 characters or- more, the second word , 

of its I/O status would be set to 10 and 10 characters would be 
ttansferred. A special I/O function, lO.STC, returns status to an 
offspring task without a data transfer. The parameter word format for 
the lO.STC function is as follows: 

;:::?- Viotd bit set, indicating status" is requested "^^ 
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Word 1 is the second word of I/O return status 

Word 2 is the first word of I/O return status 

The status words are reversed in order to be similar to the format in 
which status must be passed back in a parent read or write function to 
an offspring task. The lO.STC function nust be used to return status 
when no transfer is desired, since a byte count of is not allowed in 
an lO.RLB or lO.WLB (read logical block and write logical block 
operations, respectively). For example, IE. EOF (write end-of-file 
tape mark), would normally be returned with lO.STC. 

In addition zo returning status, the lO.STC function has an additional 
purpose. It can enable or disable intermediate buffering of I/O 
requests; note that a task cannot porform both lO.STC functions in 
the same I/O request. If bit of the first parameter word in lO.STC 
is clear, bit 1 in this word is interpreted as a disable buffering 
f 1 ag : 

If bit is clear and bit 1 is set, intermediate buffering of 
offspring I/O is disabled. 

If bit is clear and bit 1 is clear, buffering is enabled. 

Buffering cai not be enabled on a virtual terminal unit that has been 
created with an "mien" parameter greater than the system-wide maximum 
specified at Sysgcn time. An attempt to do both results in an error 
return of lE.IFC. 

The only tas<s thet can assign LUNs to a virtual terminal unit are: 

(1) The task that created the virtual terminal unit 

(2) that tayk's offspring task(s) whose TI : is the virtual 
terminal unit 

Attachment of a virtual terminal unit by an offspring task prevents 
the dequeuing of 1/0 requests to that unit from other offspring tasks; 
parent I/O requests are always serviced. 

FORTRAN Call: 

CALL CRVT ( [iiast] , [ioast] , [iaast] , [imlcn] .iparm, [ids] ) 

iiast = AST address at which input requests from offspring 
tasks are serviced 

ioast = AST address at which output requests from offspring 
tasks are serviced 

iaast = AST address at which the parent task may be notified 
of the completion of successful offspring attach and 
detach requests to the virtual terminal unit 

NOTK 

At least one of the above optional 
parameters should be specified; 

otherwise, the virtual terminal created 

is treated as the null device. 
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iralen = Maximum buffer length allowed for offspring I/O 

;-irequests. 

iparm = Address of 3-word buffer to receive information from 
the stack when an AST pccurs, ■ 

ids = Integer to receive the directive status word 
containing the virtual termirial number 

Macro Call: 

CRVT$ [iast:]:,;{oasti , [aast] , [mien] j;: : . : 

last = /AST address at which input requests from offspring 
tasks: are serviced. rf:;iast=0, offspring input 
■requests are rejected with: lE.IFC returned. 

oast = AST address; at which output requests from offspring 
tasks are serviced. IE paEt=0 offspring output 
requests are rejected with lE.IFC returned. 

aast = AST :^ddress at which the: parent task may be notified jg^p,^ 
of the completion of successful offspring attach and ''' 

detach: requests to the virtual terminal unit. If 
^ast=Or no notification of offspring attach/detach is 
returned to the parent task. . 

■ .■ .NOTE ;■ 

At least one of the above .optional 

parameters should : be ■ : ^\>specif ied; 

otherwise, the virtual: terminal: created ^,,111^^ 

is treated as the null device.; ' 

mien = Maximum buffer length (bytes) allowed for offspring 
I/O: requests (default and maximum values for this 
parameter are SYSGEN options) .■ 

Macro Expansion: ■;": : 

[ASTRU,OASTRU,PAST,20, : 

;CRVT$ MACRO IJIC, DPB SIZE = 5 WORDS ^0^ 

;INPUT REQUEST AST ROUTINE ADDRESS ' 

;OUTPUT REQUESt AST ROUTINE ADDRESS 
/SUCCESSFUL VT ATTACH NOTIFICATION AST 
. /ROUTINE ADDRESS.. 
• WORD 2:Q:J;; V: ; MAXIMUM BUFF'EiaJLENGTn = 20. BYTES 

Local Symbol Definitions: 

C.RVIA — /Input ;r.iequest;AST routine Kaddiress (2) 

C.RVOA — Output request AST routine -address (2) 

C.RVAA — VT: attach notification AST: routine address (2) 

C.RVML — : Maximum "buffer length -(2) ; V; 



CRVT$ 


lASTRU 


.BYTE 


14 9:., 5 


.WORD 


iaStru 


.WORD 


OASTRU 


.WORD 


past: ■: ;. 



,-^p^^l. 
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DSW Return Codes: 

unit — Successful completion results in the return of the 
unit number of the created virtual terminal unit with 
the C bit clear 

lE.UPN — Insufficient dynamic memory to allocate the virtual 
terminal device unit data structures 

lE.HWR — Virtual terminal device driver not resident 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 

lE.SDP — Die or DPB size is invalid 
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CSRQ$ 

6.3.14 Cancel Time Based Initiation Requests 

The Cancel Time Based Initiation Requests directive instructs the 
system to cancel all time-synchronized initiation requests for a 
specified task, regardless of the source of each request. These 
requests result from a Run directive, or from any of the 
time-synchronized variations of the MCR Run command. 

In a multiuser protection system, a nonprivileged task can only cancel 
time-based initiation requests for a task with the same TI : . 

FORTRAN Call: 

CALL CANALL (tsk[,ids]) 

tsk = Task name 

ids = Directive status 

Macro Call: 

CSRQ$ tsk 

tsk = Scheduled (target) task name 

Macro Expansion: 

CSRQ$ ALPHA 

.BYTE 25., 3 ;CSRQ$ MACRO DIC, DPS SIZE=3 WORDS 

.RAD50 /ALPHA/ ;TASK "ALPHA" 

Local Symbol Definitions; 

C.SRTN — Target task name (4) 
DSW Return Codes: 

IS. sue — Successful completion 

IE. INS — Task is not installed 

lE.PRI — The issuing task is not privileged and is attempting 
to cancel requests maide by another task 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 



Note ; 



TNAME 1 



.fl^^^^ffw^ 



lE.SDP — DIC or DPB size is invalid 

If the programmer specifies an error routine address when using 
the $C or $S macro form, then a null argument must be included 
for RSX-llD compatibility. For example: f 

CSRQ$S #TNAME,,ERR /CANCEL REQUESTS FOR "ALPHA" 

.RAD50 /ALPHA/ (^^ 
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DECL$S 



6.3.15 Declare Significant Event ($S form recommended) 

The Declare Significant Event directive instructs the system to 
declare a significant event. 

Declaration of a significant event causes the Executive to scan the 
Active Task List from the beginning, searching for the highest 
priority task that Is ready to run. This directive should be used 
with discretion to avoid excessive scanning overhead. 

FORTRAN Call: 

CALL DECLAR ( [,lds] ) 

Ids = Directive status 

Macro Call: 

DECL$S [,err] 

err = Error routine address 

Macro Expansion: 



DECL$S ,ERR 

MOV {PC)+,-{SP) 

.BYTE 35., 1 

EMT 377 

BCC .+6 

JSR PC, ERR 



NOTE: THERE IS ONE IGNORED ARGUMENT 

PUSH DPS ONTO THE STACK 

DECL$S MACRO DIC, DPB SIZE=1 WORD 

TRAP TO THE EXECUTIVE 

BRANCH IF DIRECTIVE SUCCESSFUL 

OTHERWISE, CALL ROUTINE "ERR" 



Local Symbol Definitions: 

None 
DSW Return Codes: 

IS. sue — Successful completion 

lE.ADP - 



Part of the DPB is out of the Issuing task's address 
space 



lE.SDP — DIC or DPB size is invalid 



Note: 



The $S form of the macro is recommended because this directive 
requires only a 1-word DPB. 



6-45 



DIRECTIVE DESCRIPTIONS 

DSAR$S 

or 
IHAR$S 

6.3.16 Disable (or Inhibit) AST Recognition ($S form recommended) 

The Disable (or Inhibit) AST Recognition directive instructs the 
system to disable recognition of ASTs for the issuing task. The ASTs 
are queued as they occur and are effected when the task reenables AST 
recognition. There is an implied AST disable recognition directive 
whenever an AST service routine is executing. When a task's execution 
is started, AST recognition is enabled. See Notes below. 

FORTRAN Call: 

CALL DSASTR [ (ids) ] 

or 
CALL INASTR [(ids)] 

ids = Directive status 
Macro Call: 

DSAR$S [err] 

err = Error routine address 
Macro Expansion: 

;PUSH DPB ONTO THE STACK 

;DSAR$S MACRO DIC, DPB SIZE=1 WORD 

;TRAP TO THE EXECUTIVE 

; BRANCH IF DIRECTIVE SUCCESSFUL 

; OTHERWISE, CALL ROUTINE "ERR" 

Local Symbol Definitions: 

None 
DSW Return Codes: 

IS. sue — Successful completion 

IE. ITS — AST recognition is already disabled 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 

lE.SDP — DIC or DPB size is invalid 

Notes: 

1. Only the recognition of ASTs is disabled by this directive; 
the Executive still queues the ASTs. They are queued FIFO 
and will occur in that order when the task reenables AST 
recognition. 

2. The FORTRAN calls, DSASTR (or INASTR) and ENASTR (see Section 
6.3.23) exist solely to control the possible jump to the 
PWRUP routine (power-up) . FORTRAN is not designed to link to 
a system's trapping mechanism. The PWRUP routine is strictly 
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DSAR$S 


ERR 


MOV 


(PC)+,-(SP) 


.BYTE 


99. ,1 


EMT 


377 


BCC 


.+6 


JSR 


PC, ERR 



^^if^^^ 
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controlled by the system. It is the system that both accepts 
the trap and subsequently dismisses it. The FORTRAN program 
is notified by a jump to PWRUP but must use DSASTR (or 
INASTR) and ENASTR to ensure the integrity of FORTRAN data 
structures, most importantly the stack, during power-up 
processing . 

3. Because this directive requires only a 1-word DPB, the $S 
form of the macro is recommended. It requires less space and 
executes with the same speed as the DIR$ macro. 



W^ 



6-47 



DIRECTIVE DESCRIPTIONS 

DSCP$S 

6.3.17 Disable Checkpointing ($S form recommended) 

The Disable Checkpointing directive instructs the system to disable 
the checkpointability of a task that has been installed as a 
checkpointable task. This directive can be issued only by the task 
that is to be affected. A task cannot disable the ability of another 
task to be checkpointed . 

FORTRAN Call: 

CALL DISCKP 

ids = Directive status 

Macro Call; 

DSCP$S [err] 

err = Error routine address 

Macro Expansion: 

DSCP$S ERR 

MOV (PC)+,-(SP) ;PUSH DPB ONTO THE STACK 

.BYTE 95., 1 ;DSCP$S MACRO DIC, DPB SIZE=1 WORD 

EMT 377 ;TRAP TO THE EXECUTIVE 

BCC .+6 ; BRANCH IF DIRECTIVE SUCCESSFUL 

JSR PC, ERR ; OTHERWISE, CALL ROUTINE "ERR" 

Local Symbol Definitions: 

None 
DSW Return Codes: 

IS. sue — Successful completion 

IE. ITS — Task checkpointing is already disabled 

lE.CKP — Issuing task is not checkpointable 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 

lE.SDP — DIC or DPB size is invalid 

Notes: 

1. When a checkpointable task's execution is started, 
checkpointing is enabled (that is, the task can be 
checkpointed) . 

2. Because this directive requires only a 1-word DPB, the $S 
form of the macro is recommended. It requires less space and 
executes with the same speed as the DIR$ macro. 



,#^8^*'^^ 
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DTRG$ 



6.3.18 Detach Region 

The Detach Region directive detaches the issuing task from a 
specified, previously attached region. Any of the task's windows that 
are currently mapped to the region are automatically unmapped. 

If RS.MDL is set in the region status word when the directive is 
issued, the task marks the region for deletion on the last detach. A 
task must be attached with delete access to mark a region for 
deletion. 

FORTRAN Calls 

CALL DTRG (irdb[,ids]) 

irdb = An 8-word integer array containing a Region Definition 
Block (see Section 3.5.1.2) 

ids = Directive status 
Macro Call: 

DTRG$ rdb 

rdb := Region Definition Block address 

Macro Expansion: 

iADR 

;DTRG$ MACRO DIC, DPB SIZE=2 WORDS 
;RDB ADDRESS 

Region Definition Block Parameters: 

Input parame ters 

Array 

Element Offset 

irdb(l) R.GID — ID of the region to be detached 

irdb(7) R.GSTS — Bit setting&l in the region status word: 

RS.MDL — 1 if the region should be marked 
for deletion when the last task 
detaches from it 

Output par am eters 

irdb(7) R.GSTS — Bit settings^ in the region status word: 

RS.UNM — 1 if any windows were unmapped 
Local Symbol Definitions: 

D.TRBA — Region Definition Block address (2) 



DTRG$ 


RDBADR 


.BYTE 


59., 2 


.WORD 


RDBADR 



1 FORTRAN programmers should refer to Section 3.5.1 to determine the 
bit values represented by the symbolic names described. 
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DSW Return Codes: 

IS. sue — Successful completion 

lE.PRI — The task, which is not attached with delete access, 
has attempted to mark the region for deletion on the 
last detach, or the task has outstanding I/O (not 
necessarily to this region) 

lE.NVR — The task specified an invalid region ID or attempted 
to detach region (its own task region) 

lE.ADP — Part of the DPD or RDB is out of the issuing task's 
address space 

lE.SDP — Die or DPB size is invalid 



■^ 



.r^^^^ 
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6.3.19 Eliminate Address Window 

The Eliminate Address Window directive deletes an existing address 
window, unmapping it first if necessary. Subsequent use of the 
eliminated window's ID is invalid. 

FORTRAN Call: 

CALL ELAW (iwdb[,ids]) 

iwdb = A Window Definition Block composed of an 8-word 
integer array (see Section 3.5.2.2) 

ids = Directive status 

Macro Call: 

ELAW$ wdb 

wdb = Window Definition Block address 

Macro Expansion: 

ELAW$ WDB ADR 

.BYTE 119., 2 ;ELAW$ MACRO DIC, DPB SIZE=2 WORDS 

.WORD WDBADR ;WDB ADDRESS 

Window Definition Block Parameters: 

Input param eters 

Array 

Element Offset 

iwdb(l) W.NID — ID of the address window to be eliminated 
bits 0-7 

Output parameters 

iwdb(7) W.NSTS — Bit settingsl in the window status word: 

WS.ELW — 1 if the address window was 
successfully eliminated 

WS.UNM — 1 if the address window was 
unmapped 

Local Symbol Definitions: 

E.LABA — Window Definition Block address (2) 
DSW Return Codes: 

IS. sue — Successful completion 

lE.NVW — Invalid address window ID 



1 FORTRAN programmers should refer to Section 3.5.2 to determine the 
bit values represented by the symbolic names described. 
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lE.ADP — Part of the DPB or WDB is out of the issuing task's 
address space 

lE.SDP — Die or DPB size is invalid 
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6.3.20 Eliminate Group Global Event Flags 

The Eliminate Group Global Event Flags directive marks group-global 
event flags for deletion. If no tasks in this group are waiting for 
group-global event flags (the count for this group maintained by the 
Executive in G.CNT is 0), the Group Global Event Flags Control Block 
(GFB) is immediately unlinked and deallocated. If tasks are waiting 
for flags in this group, the Executive marks the flags for deletion 
(GS.DEL is set to 1) and the GFB is eliminated when no remaining tasks 
are waiting for flags in this group; however, if a Create Group 
Global Event Flags directive is issued before the flags are 
eliminated, the Executive clears GS.DEL. 

FORTRAN CALL: 

CALL ELGF ( [group] ,[ ids] ) 

group = Group number of flags to be eliminated. Only 
privileged tasks can specify group numbers other than 
the issuing task's group UIC. If not specified, the 
task's protection UIC (H.CUIC+1) in the task's header 
is used. 

ids = Integer to receive the Directive Status Word 

Macro Call: 

ELGF$ [group] 

group = Group number of flags to be eliminated. Only 
privileged tasks can specify group numbers other than 
the issuing task's group UIC. If not specified, the 
task's protection UIC (H.CUIC+1) in the task's header 
is used. 

Macro Expansion: 

ELGF$ 303 

.BYTE 159., 2 ;ELGF$ MACRO DIC, DPB SIZE = 2 WORDS 

.WORD 303 ;GROUP NUMBER 303 FLAGS 

Local Symbol Definitions: 

E.LGRP — Group number (2) 
DSW Return Codes: 

IS. sue — Successful completion 

lE.PRI — Privilege violation 

lE.IUI — Invalid group 

lE.IEF — Group not found 

lE.RSU — Event flags are already marked for deletion 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 

IE. DIC — DIC or DPB size is invalid 
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6.3.21 Eliminate Virtual Terminal ^ ^ ^^^^ ^^^^^^ 

This direciive dauses the specified: virtual terminal unit data 
structures to be; jria-rked for deallocation and eventually to be unlinked ' 
froiti the device list and deallocated. This directive can only be : 
issued by the -task tha^ the virtual terminal device unit. Any 
active nonpriviieged tasks are aborted whose TI: device units are the 
virtual terminal being deallocated. TKTN messages reporting the abort 
of these tasks in -this instance are directed to CO:. Any LUNs 
assigned byxthe issuing task, or by any of fspring task being aborted, 
are deassigned:.'-;-;.: ■■■.■■ - ■ ■.:--y^ ■ 

A rundown cptirit is maintained in the TCB of each parent task. This 

count reflects the total number of oUtstahding virtual terminal units 

the task has -created ,: plus the'; niamber of connected (offspring) tasks. 

A series of :E;tyT$:^«iirectiv6S ^re issued whe a parent task, which has 

not eliminated virtual terminals it has created, exits. The virtual 

terminal data : structures continue to exist until the last task exits -|_. 

whose TI: is the virtual terminal unit and all CLI commands for that ' ^ 

unit have been ipirocessed . ■ 

FORTRAN Call^- : : V- : ■ ■ 

CALL ELVTvCiunum/ [ids] ): ; /"■:^^^^Vr^ 

iunurrvsfr Virtual terminal unit number 

ids ■;/-: Integer to recei^^^ Status Word 

Macro Call:-;.^\ "^^^ 

ELVT$ ;.:.;unum-,; 

unum; >^ U^^^ virtual terminal to be eliminated. 

The: task must provide this parameter after the 
-fVV.: virtual terminal is created: (see Note) . 

Macro Expansion:: 

ELVT$ :■■■■v.v:o^V;t^■■■■ ■;■..■.■■■• ■■■^::.-..- ■■ ^_^ 

.BYTE \ : 15i;:,2 ;ELVT$ MACRO Die, DPB SIZE = 2 WORDS ""^ 

.WORD - ..:0 ;:;,::,-; ^.;:^^^^^ /VIRTUAL TERMINAL UNIT NUMBER 

Local Sy^bol'^De;fihitioriS: : ^ - 

E.LVNM:-- ^ VT unit number (2);: 
DSW Return Codes: ■'; 

IS. sue r-- : Successful completion; 

IE.IDu;:--rr The specified virtual terminal unit does not exist or 

:.:-;:>: it Was not created by the -issuing task 

lE.ADP -- Part of the DPB is put of the issuing task's addresa 

■-■.;.■.■.:..■;. space ■ 

I E . SDP ;. ,^r., ■■■:;.DXC'- or^vOpB' size.-is- Vinval-id'^-V^ 
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Note ! 



The actual virtual terminal unit number is not known until after 
the virtual terminal is actually created (that is, after 
successfully completing a Create virtual Terminal directive). 
The Create Virtual Terminal directive DSW contains the actual 
virtual terminal unit number for use in the Eliminate virtual 
Terminal directive. Thus, the task must save DSWs for all 
virtual terminals it creates, and later eliminate them using the 
Eliminate Virtual Terminal Directive. 
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iiy)ST$ 



;6v3i22 Emit Status 



The Emit status directive returns the specified 16-bit quantity to the 
speGified connected task, possibly setting an event flag or declaring 
an AST if previously specified by the connected task in a Send, 
Request And Connect, a Spawn, or a Connect directive. If no task name 
is specified, this action is taken for all tasks which are connected 
to the issuing task at that time. If the specified task is multiply 
connected to : the task issuing this directive, the first (oldest) 
Offspring ; Control Block (GOB) in the queue is used to return status. 
In any case, whenever status is emitted to one or more tasks, those 
tasks : no longer remain connected to the task- issuing the Emit Status 
directive. ■ ■ 

FORTRAN Call: :/ ■■. 

CALL EMST { [rtname] , status [, ids] } 

rthame ==; Name of task connected to issuing task to which the 
status is to be emitted , / ■; ; 

status := 16-bit quantity to be returned to the connected task 

id:s = -Integer to receive the Directive Status Word 

Macro -Call r^--:' 

EMST$ itnarte] , Status; ■ : 



tn^me = Name of a task connected :t6; the issuing task to 

jyhich the status is to be emmitted 

status :== ;16-bit; quantity to be returned to the connected task 

Macro Expansion: 

EMST$; ALPHA, STWD 

•BYTE ;: 147. ,4 : : ;EMST$ MACRO DIC,: DPS SIZE=4 WORDS 

.RAD50: alpha: ; NAME OF CONNECTED TASK TO RECEIVE STATUS 

.WORD :; STWD : ;VALUE OF STATUS TO BE RETURNED 



Local Symbol Definitions: 

E.MSTN;— Task name (4) 

E.MSST —-■Status to be returned: (2);: 
DSW Return Codes: : 

IS.SUC ;:: — Successful completion 

lE.lTS-- the specified task is not connected to the issuing 
■ task ' ■.■:... 

lE.ADP: -- Part of the DPB is out of; the issuing task's address 
■ space- ■■. 



lE.SDP :— Die or DPB size is invalid 



/^^™™re2i 
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6.3.23 Enable AST Recognition ($S form recommended) 

The Enable AST Recognition directive instructs the system to recognize 
ASTs for the issuing task; that is, the directive nullifies a Disable 
AST Recognition directive. ASTs that were queued while recognition 
was disabled are effected at issuance, when a task's execution is 
started, AST recognition is enabled. 

FORTRAN Call: 

CALL ENASTR [(ids)] 

ids = Directive status 

Macro Call: 

ENAR$S [err] 

err = Error routine address 

Macro Expansion: 



;PUSH DPB ONTO THE STACK 

;ENAR$S MACRO DIC, DPB SIZE=1 WORD 

;TRAP TO THE EXECUTIVE 

;BRANCE IF DIRECTIVE SUCCESSFUL 

;OTHERWISE, CALL ROUTINE "ERR" 



ENAR$S ERR 

MOV (PC)+,-(SP) 

.BYTE 101. ,1 

EMT 377 

BCC .+6 

JSR PC, ERR 

Local Symbol Definitions: 

None 
DSW Return Codes: 

IS. sue — Successful completion 

IE. ITS — AST recognition is not disabled 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 

lE.SDP — DIC or DPB size is invalid 

Notes: 

1. Because this directive requires only a 1-word DPB, the $S 
form of the macro is recommended. It requires less space and 
executes with the same speed as the DIR$ macro. 



The FORTRAN calls DSASTR (or I 
ENASTR exist solely to contro 
(power-up) . FORTRAN is not de 
trapping mechanism. The PWRUP 
by the system. It is the syst 
and subsequently dismisses 
notified by a jump to PWRUP bu 
and ENASTR to ensure th 
structures, most importantly 
processing. 



NASTR) (see Section 6.3.16) and 
1 the jump to the PWRUP routine 
signed to link to a system's 
routine is strictly controlled 
em which both accepts the trap 
it. The FORTRAN program is 
t must use DSASTR (or INASTR) 
e integrity of FORTRAN data 
the stack, during power-up 
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ENCP$S 

6.3.24 Enable Checkpointing ($S form recommended) 

The Enable Checkpointing directive instructs the system to make the 
issuing task checkpointable after its checkpointability has been 
disabled; that is, the directive nullifies a DSCP$S directive. 

FORTRAN Call: 

CALL ENACKP 

ids = Directive status 

Macro Call: 

ENCP$S [err] 

err = Error routine address 

Macro Expansion: 



ENCP$S ERR 

MOV (PC)+,-(SP) 

•BYTE 97., 1 

EMT 377 

BCC .+6 

JSR PC, ERR 



PUSH DPB ONTO THE STACK 

ENCP$S MACRO DIC, DPB SIZE=1 WORD 

TRAP TO THE EXECUTIVE 

BRANCH IF DIRECTIVE SUCCESSFUL 

OTHERWISE, CALL ROUTINE "ERR" 



Local Symbol Definitions: 

None 
DSW Return Codes: 

IS. sue — Successful completion 

IE. ITS — Checkpointing is not disabled or task is connected to 
an interrupt vector 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 



lE.SDP — DIC or DPB size is invalid 



Note : 



Because this directive requires only a 1-word DPB, the $S form of 
the macro is recommended. It requires less space and executes 
with the same speed as the DIR$ macro. 






-^ff^W^ 
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6.3.25 Exit If 

The Exit If directive instructs the system to terminate the execution 
of the issuing task if, and only if, an indicated event flag is NOT 
set. The Executive returns control to the issuing task if the 
specified event flag is set. See Notes below. 

FORTRAN Call: 

CALL EXITIF (efn[,ids]) 

efn = Event flag number 

ids = Directive status 

Macro Call: 

EXIF$ efn 

efn = Event flag number 

Macro Expansion: 

EXIF$ 52. 

.BYTE 53., 2 ;EXIF$ MACRO DIC, DPB SIZE=2 WORDS 

.WORD 52. ; EVENT FLAG NUMBER 52. 

Local Symbol Definitions: 

E.XFEF — Event flag number (2) 

DSW Return Codes: 

IS. SET — Indicated EFN set, task did not exit 

lE.IEF — Invalid event flag number (EFN>64 or EFN<1) 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 

lE.SDP — DIC or DPB size is invalid 

Notes: 

1. The Exit If directive is useful in avoiding a possible race 
condition that can occur between two tasks communicating via 
the Send and Receive directives. The race condition occurs 
when one task executes a Receive directive and finds its 
receive queue empty; but before the task can exit, the other 
task sends it a message. The message is lost because the 
Executive flushed the receiver task's receive queue when it 
decided to exit. This condition can be avoided if the 
sending task specifies a common event flag in the Send 
directive and the receiving task executes an Exit If 
specifying the same common event flag. If the event flag is 
set, the Exit If directive will return control to the issuing 
task, signaling that something has been sent. 

2. A FORTRAN program that issues the Exit If call must first 
close all files by issuing Close calls. See the IAS/RSX-11 
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FORTRAN IV or FORTRAN IV-PLUS User's Guide for instructions 
on how to ensure that such files are closed properly if the 
task exits. To avoid the time overhead involved in the 
closing and reopening of files, the task should first issue 
the appropriate test or clear event flag directive. If the 
directive status word, indicates that the flag was not set, 
then the task can close all files and issue the call to Exit 
If. 

On Exit, the Executive frees task resources. In particular, 
the Executive: 

• Detaches all attached devices 

• Flushes the AST queue 

• Flushes the receive and receive-by-reference queues 

• Flushes the clock queue for any outstanding Mark Time 
requests for the task 

• Closes all open files (files open for write access are 
locked) 

• Detaches all attached tasks, except in the case of a 
fixed task in a system that supports the memory 
management directives 

• Runs down the task's I/O 

• Frees the task's memory if the exiting task was not 
fixed 

• Marks all virtual termlial units the task has created 
for deallocation (see Section 5.2) 

• Disconnects all connected tasks 

If the task exits, the Executive declares a significant 
event. 



^^fh. 
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6.3.26 Task Exit ($S form recommended) 

The Task Exit directive instructs the system to terminate the 
execution of the issuing task. 

FORTRAN Call: 

CALL EXIT 

or 
STOP [messg] 

messg = Optional 1- to 26-character string to be displayed 
when the STOP statement is executed 

Macro Call: 

EXIT$S [err] 

err = Error routine address 

Macro Expansion: 



EXIT$S ERR 

MOV (PC)+,-(SP) 

•BYTE 51., 1 

EMT 377 

JSR PC, ERR 

Local Symbol Definitions; 

None 

DSW Return Codes: 



PUSH DPB ONTO THE STACK 

EXIT$S MACRO DIC, DPB SIZE=1 WORD 

TRAP TO THE EXECUTIVE 

CALL ROUTINE "ERR" 



lE.ADP — Part of the DPB is out of the issuing task's address 
space 

lE.SDP — DIC or DPB size is invalid 

Notes: 

1. A return to the task occurs if, and only if, the directive is 
rejected. Therefore, no Branch on Carry Clear instruction is 
generated if an error routine address is given, since the 
return will only occur with carry set. 

2. Exit causes a significant event. 

3. On Exit, the Executive frees task resources. In particular, 
the Executive: 

• Detaches all attached devices 

• Flushes the AST queue 

• Flushes the receive and receive-by-reference queues 

• Flushes the clock queue for any outstanding Mark Time 
requests for the task 
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• Closes all open files (liiles open for write access are 
locked) 

• Detaches all attached regions, except in the case of a 
fixed task, where no detaching occurs 

• Runs down the task's I/O 

• Frees the task's memory if the exiting task was not 
fixed 

• Marks all virtual terminal units the task has created 
for deallocation (see Section 5.2) 

• Disconnects all connected tasks 

4. Because this directive requires only a 1-word DPB, the $S for 
of the macro is recommended. It requires less space and 
executes with the same speed as the DIR$ macro. 

5. FORTRAN tasks that terminate with the STOP statement result 
in a message being displayed on the task's TI : . This message 
includes task name (as it appears in the Active Task List) , 
the statement causing the task to stop, and an optional 
character string specified in the STOP statement. Tasks that 
terminate with CALL EXIT do not display a termination 
message. For example, a FORTRAN task containing the 
following statement: 

20 STOP 'THIS FORTRAN TASK' 

exits with the following message displayed on the tasks TI : 
(TT37 in this example) : 

TT37 — STOP THIS FORTRAN TASK 



,w™'^^% 
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6.3.27 Exit With Status 

The Exit With Status directive causes the issuing task to exit, 
passing a 16-bit status back to all tasks connected (via the Spawn, 
Connect, o r ^^«i)t;,i?v;^i^;|^lf ;i|(ri|Bsgi|j^^fi^^ If the issuing task 

has no corinected tasks,' tKeri 'the directive simply performs a Task 

Exit. No format of the status word is enforced by the Executive; 
format conventions are a function of the cooperation between parent 
and offspring tasks. However, if an offspring task aborts for any 
reason, a status of EX$SEV is returned to the parent task. :Tih,l'a^\'?«i'u« ,' 
■BMnB^K^^^m^^KM9^BMBBsS0MMS^SffMSK^Sl^^^^^ Furthermore, 

if a task performs a normal exit with other tasks connected to it, a 

status of EX$SUC (successful completion) is returned to all connected 
tasks. 

FORTRAN Call: 

CALL EXST (Status) 

status = 16-bit quantity to be returned to parent task 

Macro Call: 

EXST$ status 

status = 16-bit quantity to be returned to parent task 

Macro Expansion: 

EXST$ STWD 

.BYTE 29., 2 ;EXST$ MACRO DIC, DPB SIZE = 2 WORDS 

.WORD STWD ;VALUE OF STATUS TO BE RETURNED 

Local Symbol Definitions: 

E.XSTS — Value of status to be returned (2) 

DSW Return Codes: 

No status is returned if the directive is successfully completed 
since the directive causes the issuing task to exit. 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 

lE.SDP — DIC or DPB size is invalid 
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inc = A positive or negative number equal to the number of 
32-word blocks by which the task size is to be extended 
or reduced 
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6.3.28 Extend Task 

The Extend Task directive instructs the system to modify the size of 
the issuing task by a positive or negative increment of 32-word 
blocks. If the directive does not specify an increment value, the 
Executive makes the issuing task's size equal to its installed size. 
The issuing task must be running in a system-controlled partition, 
must not use memory-resident overlays, and cannot have any outstanding 
I/O when it issues the directive. The task must also be 
checkpointable to increase its size; if necessary, the Executive 
checkpoints the task, then returns the task to memory with its size 
modified as directed. 

In a system that supports the memory management directives, the 

Executive does not change any current mapping assignments if the task 

has memory-resident overlays. However,, if the task does not have 

memory-resident overlays, the Executive attempts to modify, by the 

specified number of 32-word blocks, the mapping of the task to its . jMik, 

task region. I' 

If the issuing task is checkpointable but has no preallocated 
checkpoint space available, a positive increment may require dynamic 
memory and extra space in a checkpoint file sufficient to contain the 
task. 

There are several constraints on the size to which a task can extend 
itself using the Extend directive: 

• No task can extend itself beyond the maximum size set by the ^0th, 
MCR command SET /MAXEXT or the size of the partition in which "' 
it is running. (See the RSX-llM/M-PLUS MCR Operations 

Manual . ) 

• A task that does not have memory-resident overlays cannot 
extend itself beyond 32K minus 32 words. 

• A task that has preallocated checkpoint space in its task 
image file cannot extend itself beyond its installed size. 

• A task that has memory-resident overlays cannot reduce its Ji%^ 
size. 

FORTRAN Call: 

CALL EXTTSK ( [ inc] [ , ids] ) 

inc = A positive or negative number equal to the number of 
32-word blocks by which the task size is to be extended 
or reduced 

ids = Directive status 

Macro Call: 

EXTK$ [inc] 
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Macro Expansion; 



EXTK$ 
.BYTE 
• WORD 



40 

89. ,3 
40 



;EXTK$ MACRO DIG, DPB SIZE=3 WORDS 
;EXTEND INCREMENT, 40(8) BLOCKS (IK 
; WORDS) 
; RESERVED WORD 



.WORD 
Local Symbol Definitions: 

E.XTIN — Extend increment (2) 
DSW Return Codes: 

IS. sue — Successful completion 

lE.UPN — Insufficient dynamic memory, or insufficient space in 
a checkpoint file 

IE. ITS — Task has memory-resident overlays and is attempting 
to reduce its size 

lE.ALG — The issuing task attempted to reduce its size to less 
than the size of its task header; or the task tried 
to increase its size beyond 32K words or beyond the 
maximum set by the MCR SET /MAXEXT command; or the 
task tried to increase its size to the extent that 
one virtual address window would overlap another 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 

lE.RSU — Other tasks are attached 

lE.IOP — I/O is in progress 

lE.CKP — Task is not checkpointable and specified a positive 
integer 

IE. NSW — Attempt to extend to larger than installed size (when 
checkpoint space is allocated in the task) 

lE.SDP — Die or DPB size is invalid 
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6.3.29 Get LUN Information 

The Get LUN Information directive instructs the system to fill a 
6-word buffer with information about a physical device unit to which a 
LUN is assigned. If requests to the physical device unit have been 
redirected to another unit, the information returned will describe the 
effective assignment. 

FORTRAN Calls 

CALL GETLUN (lun ,dat [ , ids] ) 

lun = Logical unit number 

dat = 6-word integer array to receive LUN information 

ids = Directive status 

Macro Call: 

GLUN$ lun,buf 

lun = Logical unit number 

buf = Address of 6-word buffer that will receive the LUN 
information 

Buffer Format: 

word — Name of assigned device 

word 1 — Unit number of assigned device and flags byte (flags 
byte equals 200 if the device driver is resident or 
if the driver is not loaded) 

word 2 — First device characteristics word: 

Bit — Record-oriented device (l=yes) [FD.REC]! 

Bit 1 — Carriage-control device (l=yes) [FD.CCL] 

Bit 2 — Terminal device (l=yes) [FD.TTY] 

Bit 3 — Directory (file-structured) device 
(l=yes) [FD.DIR] 

Bit 4 — Single directory device (l=yes) [FD.SDI] 

Bit 5 — Sequential device (l=yes) [FD.SQD] 

Bit 6 — Reserved 

Bit 7 — User-mode diagnostics supported (l=yes) 

Bit 8 — Massbus device (l=yes) 

Bit 9 — Unit softv\/are write-locked (l=yes) 

Bit 10 — Input spooled device (l=yes) 
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Bit 11 — Output spooled device (l=Yes) 

Bit 12 — pseudo device (l=yes) 

Bit 13 — Device mountable as a communications 
channel (l=yes) 

Bit 14 — Device mountable as a Files-11 device 
(l=yes) 

Bit 15 — Device mountable (l=yes) 

word 3 — Second device characteristics word 

word 4 — Third device characteristics word (words 3 and 4 are 
device driver specific) 



wo 



rd 5 — Fourth device characteristics word 



Macro Expansion: 

GLUN$ 7,LUNBUF 

.BYTE 5,3 

•WORD 7 

.WORD LUNBUF 



GLUN$ MACRO DIG, DPB SIZE=3 WORDS 
LOGICAL UNIT NUMBER 7 
ADDRESS OF 6-WORD BUFFER 



Local Symbol Definitions: 

G.LULU — Logical unit number (2) 

G.LUBA — Buffer address (2) 

The following offsets are assigned relative to the start of the LUN 
information buffer: 

G.LUNA — Device name (2) 

G.LUNU — Device unit number (1) 

G.LUFB — Flags byte (1) 

G.LUCW — Four device characteristics words (8) 
DSW Return Codes: 

IS. sue — Successful completion 

lE.ULN — Unassigned LUN 

lE.ILU — Invalid logical unit number 



- Part of the DPB or buffer is out of the issuing 
task's address space 



lE.ADP 

lE.SDP — Die or DPB size is invalid 



1 Bits with associated symbols have the symbols shown in square 
brackets. These symbols can be defined for use by a task via the 
FCSBT$ macro. See the IAS/RSX-11 I/O Operations Reference Manual . 
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Note : 

If a spooled device is found in the redirection chain and the "^^ 
issuing task is not the despooler, the LUN information returned 
by the Executive is as follows: 

word — name of assigned (spooled) device 

word 1 — unit number of assigned spooled device and flags 
byte 

word 2 — intermediate device (for example, a disk) first 
device characteristics word ORed with the output 
spool bit (spooled device first characteristics 
word, bit 11) 

word 3 — spooled device fourth device characteristics word 

word 4 — not defined 

word 5 — intermediate device standard device buffer size 



^p9fl^B^ 
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6.3.30 Get MCR Command Line 

The Get MCR Command Line directive instructs the system to transfer an 
80-lbyte command line to the issuing task. 

When a task is installed with a task name of "...tsk" or "tskTn", 

where "tsk" consists of three alphanumeric characters and n is an 

octal terminal number, the MCR dispatcher requests the task's 
execution when a user issues the command: 

>tsk command-line 

from terminal number n. A task invoked in this manner must execute a 
call to Get MCR Command Line, which results in the entire "command 
line" following the prompt being placed into an 80-byte command line 
buffer. (The MCR dispatcher is described in the RSX-llM/M-PLUS MCR 
Operations Manual . ) 

FORTRAN Call: 

CALL GETMCR (buf[,ids]) 

buf = 80-byte array to receive command line 



ids 


= Direct 


Macro Call: 






GMCR$ 






Macro Expansion: 




GMCR$ 






.BYTE 


127. 


,41. 


.BLKW 


40. 





;GMCR$ MACRO DIC, DPB SIZE=41. WORDS 
;80. CHARACTER MCR COMMAND LINE BUFFER 

Local Symbol Definitions: 

G.MCRB — MCR line buffer (80) 

DSW Return Codes: 

+n — Successful completion; n is the number of data bytes 
transferred (excluding the termination character) • 
The termination character is, however, in the buffer. 

lE.AST — No MCR command line exists for the issuing task; 
that is, the task was not requested by a command line 
as follows: 

>tsk command-string 

or the task has already issued the Get MCR Command 
Line directive. 

lE.ADP — Part of the DPB is out of the issuing task's address 
space. 

lE.SDP — DIC or DPB size is invalid. 
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Notes: 



1. The GMCR$S form of the macro is not supplied, since the DPB ^^. 
receives the actual command line. ''' 

2. The system processes all lines to: 

• Convert tabs to a single space 

• Convert multiple spaces to a single space 

• Convert lower case to upper case 

• Remove all trailing blanks 

The terminator (<CR> or <ESC>) is the last character in the 
line. 



i^fl^^k 
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6.3.31 Get Mapping Context 

The Get Mapping Context directive causes the Executive to return a 
description of the current window-to-region mapping assignments. The 
returned description is in a form that enables the user to restore the 
mapping context through a series of Create Address Window directives 
(see Section 6.3.10). The macro argument specifies the address of a 
vector that contains one Window Definition Block (WDB) for each window 
block allocated in the task's header, plus a terminator word. 

For each window block in the task's header, the Executive sets up a 
WDB in the vector as follows: 

1. If the window block is unused (that is, if it does not 
correspond to an existing address window) , the Executive does 
not record any information about that block in a WDB. 
Instead, the Executive uses the WDB to record information 
about the first block encountered that corresponds to an 
existing window. In this way, unused window blocks are 
ignored in the mapping context description returned by the 
Executive. 

2.' If a window block describes an existing unmapped address 
window, the Executive fills in the offsets W.NID, W.NAPR, 
W.NBAS, and W.NSIZ with information sufficient to recreate 
the window. The window status word W.NSTS is cleared. 

3. If a window block describes an existing mapped window, the 
Executive fills in the offsets W.NAPR, W.NBAS, W.NSIZ, 
W.NRID, W.NOFF, W.NLEN, and W.NSTS with information 
sufficient to create and map the address window. WS.MAP is 
set in the status word (W.NSTS), and if the window is mapped 
with write access, the bit WS.WRT is set as well. 

Note that in no case does the Executive modify W.NSRB. 

The terminator word, which follows the last WDB filled in, is a word 
equal to the negative of the total number of window blocks in the 
task's header. It is thereby possible to issue a TST or TSTB 
instruction to detect the last WDB used in the vector. The 
terminating word can also be used to determine the number of window 
blocks built into the task's header. 

When Create Address Window directives are used to restore the mapping 
context, there is no guarantee that the same address window IDs will 
be used. The user must therefore be careful to use the latest window 
IDs returned from the Create Address Window directives. 

FORTRAN Call: 

CALL GMCX (imcx[,ids]) 

imcx = An integer array to receive the mapping context. The 
size of the array is 8*n+l where n is t.he number of 
window blocks in the task's header. The maximum size 
is 8*8+1=65 words. 

ids = Directive status 



6-71 



DIRECTIVE DESCRIPTIONS 



Macro Call: 
GMCX$ 



wvec 



wvec = The address of a vector of n Window Definition Blocks, 
followed by a terminator word; n is the number of 
window blocks in the task's header 



Macro Expansion: 



GMCX$ 
• BYTE 
.WORD 



VECADR 
113. ,2 
VECADR 



;GMCX$ MACRO DIC, DPB SIZE=2 WORDS 
;WDB VECTOR ADDRESS 



Window Definition Block Parameters! 
Input parameters 

None 
Output parameters 



Array 
Element 

iwdb(l) 
bits 0-7 

iwdb(l) 
bits 8-15 

iwdb(2) 

iwdb(3) 

iwdb{4) 

iwdb(5) 



iwdb(6) 



Offset 

W.NID — ID of address window 

W.NAPR — Base APR of the window 

W.NBAS — Base virtual address of the window 

W.NSIZ — Size, in 32-word blocks, of the window 

W.NRID — ID of the mapped region, or no change if 
the window is unmapped 

W.NOFF — Offset, in 32-word blocks, from the start 
of the region at which mapping begins, or 
no change if the window is unmapped 

W.NLEN — Length, in 32-word blocks, of the area 
currently mapped within the region, or no 
change if the window is unmapped 

W.NSTS — Bit settingsl in the window status word 
(all if the window is not mapped) : 

WS.MAP — 1 if the window is mapped 

WS.WRT — 1 if the window is mapped 
with write access 

Note that the length mapped (W.NLEN) can be less than the size of 
the window (W.NSIZ) if the area from W.NOFF to the end of the 
partition is smaller than the window size. 



iwdb(7) 



,^^^|i 



.(WmH^Hk 



1 FORTRAN programmers should refer to Section 3.5.2 to determine the 
bit values represented by the symbolic names described. 
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Local Symbol Definitions: 

G.MCVA — Address of the vector (wvec) containing the window 
definition blocks and terminator word (2) 

DSW Return Codes: 

IS. sue — Successful completion 

lE.ADP — Address check of the DPB or the vector (wvec) failed 

lE.SDP — Die or DPB size is invalid 

Note: 

If the window is mapped in Supervisor mode, bit WS.SIS is set in 
the Vi/DB status word V/.NSTS. 
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6.3.32 Get Partition Parameters 

The Get Partition Parameters directive instructs the system to fill an 
indicated 3-word buffer with partition parameters. If a partition is 
not specified, the partition of the issuing task is assumed. 

FORTRAN Call: 

CALL GETPAR ( [pr t] ,buf [ , ids] ) 

prt = Partition name 

buf = 3-word integer array to receive partition parameters 

ids = Directive status 
Macro Call: 

GPRT$ [prt] ,buf 

prt = Partition name 

buf = Address of a 3-word buffer 
Buffer Format: 

word — Partition physical base address expressed as a 
multiple of 32 words (partitions are always aligned 
on 32-word boundaries) . Therefore, a partition 
starting at 40000(8) will have 400(8) returned in 
this word. 



wo 



£■(3 I — Partition size expressed as a multiple of 32 words. 



word 2 — Partition flags word. This word is returned equal 
to to indicate a system-controlled partition, or 
equal to 1 to indicate a user-controlled partition. 



Macro Expansion: 

GPRT$ ALPHA, DATBUF 

.BYTE 65. ,4 

.RAD50 /ALPHA/ 

.WORD DATBUF 



GPRT$ Die, DPB SIZE=4 WORDS 
PARTITION "ALPHA" 
ADDRESS OF 3-WORD BUFFER 



Local Symbol Definitions: 

G.PRPN — Partition name (4) 

G.PRBA — Buffer address (2) 

The following offsets are assigned relative to the start of the 
partition parameters buffer: 

G.PRPB — Partition physical base address expressed as an 
absolute 32-word block number (2) 
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G.PRPS — Partition size expressed as a multiple of 32-word 
blocks (2) 

G.PRFW — Partition flags word (2) 

DSW Return Codes: 

Successful completion is indicated by a cleared Carry bit, and 
the starting address of the partition is returned in the DSW. 
The returned address is a physical address expressed in 32-word 
blocks. Unsuccessful completion is indicated by a set Carry bit 
and one of the following codes in the DSW: 

IE. INS — Specified partition not in system 

lE.ADP — Part of the DPB or buffer is out of the issuing 
task's address space 

lE.SDP — Die or DPB size is invalid 

Notes: 

1. fi'or Executives that support the memory management directives, 
a variation of this directive exists called Get Region 
Parameters (see Section 6.3.33). When the first word of the 
2-word partition name is 0, the Executive interprets the 
second word of the partition name as a region ID. If the 
2-word name is 0,0, it refers to the task region of the 
issuing task. 

2. Omission of the partition-name argument returns parameters 
for the issuing task's unnamed subpartition, not for the 
system-controlled partition. 
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6.3.33 Get Region Parameters 

The Get Region Parameters directive instructs the Executive to fill an 
indicated 3-word buffer with region parameters. If a region is not 
specified, the task region of the issuing task is assumed. 

This directive is a variation of the Get Partition Parameters 
directive (see Section 6.3.32) for Executives that support the memory 
management directives. 

FORTRAN Call: 

CALL GETREG ( [ r id] ,buf [ , ids] ) 

rid = Region id 

3-word integer array to receive region parameters 

= Directive status 



buf 
ids 
Macro Call 
GREG$ 
rid 
buf 

Buffer Format 
word 



[rid] ,buf 
= Region ID 
= Address of a 3-word buffer 



Region base address expressed as a multiple of 32 

words (regions are always aligned on 32-word 

boundaries). Thus, a region starting at 1000(8) 
will have 10(8) returned in this word. 

word 1 — Region size expressed as a multiple of 32 words. 

word 2 — Region flags word. This word is returned equal to 
if the region resides in a system-controlled 
partition, or equal to 1 if the region resides in a 
user-controlled partition. 



Macro Expansion: 



GREG$ 
.BYTE 
.WORD 

.WORD 
.WORD 



RID,DATBUF 

65. ,4 



RID 
DATBUF 



;GREG$ MACRO DIC, DPB SIZE=4 WORDS 

;WORD THAT DISTINGUISHES GRE$ 

;FROM GPRT$ 

; REGION ID 

; ADDRESS OF 3-WORD BUFFER 



Local Symbol Definitions: 

G.RGID — Region ID (2) 
G.RGBA — Buffer address 
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The following offsets are assigned relative to the start of the region 
parameters buffer: 

G.RGRB — Region base address expressed as an absolute 32-word 
block number (2) 

G.RGRS — Region size expressed as a multiple of 32-word 
blocks (2) 

G.RGFW — Region flags word (2) 

DSW Return Codes: 

Successful completion is indicated by carry clear, and the 
starting address of the region is returned in the DSW. The 
returned address is physical. Unsuccessful completion is 
indicated by carry set and one of the following codes in the DSW: 

lE.NVR — Invalid region ID 

lE.ADP — Part of the DPB or buffer is out of the issuing 
task's address space 

lE.SDP — Die or DPB size is invalid 
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GSSW$S 

6.3.34 Get Sense Switches ($S form recommended) 

The Get Sense Switches directive instructs the system to obtain the 
contents of the console switch register and store it in the issuing 
task's Directive Status word. 

FORTRAN Call: 

CALL READSW (isw) 

isw = Integer to receive the console switch settings 

The following FORTRAN call allows a program to read the state of a 
single switch: 

CALL SSWTCH (ibt,ist) 

ibt = The switch to be tested (0 to 15) 

ist = Test results where 

1 = switch on 

2 = switch off 
Macro Call: 

GSSW$S [err] 

err = Error routine address 
Macro Expansion: 



GSSW$S ERR 

MOV (PC)+,-(SP) 

.BYTE 125. ,1 

EMT 377 

BCC .+6 

JSR PC, ERR 

Local Symbol Definitions: 

None 

DSW Return Codes: 



PUSH DPB ONTO THE STACK 

GSSW$S MACRO DIC, DPB SIZE=1 WORD 

TRAP TO THE EXECUTIVE 

BRANCH IF DIRECTIVE SUCCESSFUL 

OTHERWISE, CALL ROUTINE "ERR" 



■^^^^%j 



Successful completion is indicated by carry clear, and the 

contents of the console switch register are returned in the DSW. 

Unsuccessful completion is indicated by carry set and one of the 
following codes in the DSW: 

lE.ADP — Part of the DPB is out of the issuing task's 
address space 



lE.SDP 



DIC or DPB size is invalid 



Note I 



Because this directive requires only a 1-word DPB, the $S form of 
the macro is recommended. It requires less space and executes 
with the same speed as the DIR$ macro. 
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6.3.3 5 Get Time Parameters 

The Get Time Parameters directive instructs the system to fill an 
indicated 8-word buffer with the current time parameters. All time 
parameters are delivered as binary numbers. The value ranges (in 
decimal) are shown in the table below. 

FORTRAN Call: 

FORTRAN provides several subroutines for obtaining the time in a 
number of formats. See the lAS/RSX-llM FORTRAN IV or the FORTRAN 
IV-PLUS User's Guide . 

Macro Call: 

GTIM$ buf 

buf = Address of 8-word buffer 
Buffer Format: 

word — Year (since 1900) 

word 1 — Month (1-12) 

word 2 — Day (1-31) 

word 3 — Hour (0-23) 

word '4 — Minute (0-59) 

vford 5 — Second (0-59) 

^ord 6 — Tick of second (depends on the frequency of the 
clock) 

word 7 — Ticks per second (depends on the frequency of the 
clock) 

Macro Expansion: 

GTIM$ DATBUF 

.BYTE] 61., 2 ;GTIM$ DIG, DPS SIZE = 2 WORDS 

.WORD DATBUF ; ADDRESS OF 8. -WORD BUFFER 

Local Symbol Definitions: 

G.TIBA — Buffer address (2) 

The following offsets are assigned relative to the start of the time 
parameters buffer: 

G.TIYR — Year (2) 

G.TIMO — Month (2) 

G.TIDA — Day (2) 

G.TIHR — Hour (2) 
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G.TIMI — Minute (2) 

G.TISC — Second (2) 

G.TICT — Clock Tick of Second (2) 

G.TICP — Clock Ticks per Second (2) 

DSW Return Codes: 

IS. sue — Successful completion 

lE.ADP — Part of the DPB or buffer is out of the issuing 
task's address space 

IE. SOP — Die or DPB size is invalid 






<0m<K 
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GTSK$ 



6.3.36 Get: Task Parameters 

The Get Task Parameters directive instructs the system to fill an 
indicated 16-word buffer with parameters relating to the issuing task. 

FORTRAN Call: 

CALL GETTSK (buf[,ids]) 

buf == 16-word integer array to receive the task parameters 
ids == Directive status 
Macro Call: 

GTSK$ buf 

buf == Address of a 16-word buffer 
Buffer Format: 

word — Issuing task's name in Radix-50 (first half) 
word 1 — Issuing task's name in Radix-50 (second half) 
word 2 — Partition name in Radix-50 (first half) 
word 3 — Partition name ir^ Radix-50 (second half) 

word 4 — Undefined in RSX-llM/M-PLUS (this word exists for 
RSX-llD compatibility) 

word 5 — Undefined in RSX-llM/M-PLUS (this word exists for 
RSX-llD compatibility) 

word 6 — Run priority 

word 7 — user identification code (UIC) of issuing task (in a 
multiuser protection system, the task's default 
UIC)1 

word 10 — Number of logical I/O units (LUNs) 

word 11 — Undefined in RSX-llM/M-PLUS (this word exists for 
RSX-llD compatibility) 

word 12 — undefined in RSX-llM/M-PLUS (this word exists for 
RSX-llD compatibility) 

word 13 — (Address of task SST vector tables) 2 

word 14 — (Size of task SST vector table in words) 2 



1 See note in RQST$ description (Section 6.3.47) on contents of words 
07 and 17. 

2 Words 13 and 14 will contain valid data if word 14 is not zero. If 
word 14 is zero, the contents of word 13 are meaningless. 
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word 15 — Size (in bytes) either of task's address window in 
mapped systems, or of task's partition in unmapped 
system (equivalent to partition size) 

word 16 — System on which task is running: 

for RSX-llD 

1 for RSX-llM 

2 for RSX-llS 

3 for IAS 

4 for RSTS 

5 for VAX/VMS 

6 for RSX-llM-PLUS 

word 17 — Protection UIC (in multiuser system, the log-in 
UIC)1 

Macro Expansion: 

GTSK$ DATBUF 

•BYTE 63., 2 ;GTSK$ DIG, DPB=2-W0RDS 

.WORD DATBUF ;ADDRESS OF 16-WORD BUFFER 

Local Symbol Definitions 

G.TSBA — Buffer address (2) 

The following offsets are assigned relative to the task parameter 
buffer: 

G.TSTN — Task name (4) 

G.TSPN — Partition name (4) jH|||^ 

G.TSPR — Priority (2) 

G.TSGC — UIC group code (1) 

G.TSPC — UIC member code (1) 

G.TSNL — Number of logical units (2) 

G.TSVA — Task's SST vector address (2) 

G.TSVL — Task's SST vector length in words (2) 

G.TSTS — Task size (2) 

G.TSSY — System on which task is running (2) 

G.TSDU — Protection UIC (2) 

DSW Return Codes: 

IS. sue — Successful completion 

lE.ADP — Part of the DPB or buffer is out of the issuing 
task's address space 

lE.SDP — DIG or DPB is invalid 



1 See note in RQST$ description (Section 6.3.47) on contents of words 
07 and 17. 
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6.3.37 Map Address Window 

The Map Address Window directive maps an existing window to an 
attached region. The mapping begins at a specified offset from the 
start of the region. If the window is already mapped elsewhere, the 
Executive unmaps it before carrying out the mapping assignment 
described in the directive. 

For the mapping asssignment, a task can specify any length that is 
less than or equal to both: 

• The window size specified when the window was created 

• The length remaining between the specified offset within the 
region and the end of the region 

A task must be attached with write access to a region in order to map 
to it with write access. To map to a region with read-only access, 
the task must be attached with either read or write access. 

If W.NLEN is set to 0, the length defaults to either the window size 
or the length remaining in the region, whichever is smaller. (Since 
,the Executive returns the actual length mapped as an output parameter, 
the task must clear that parameter in the WDB before issuing the 
directive each time it wants to default the length of the map.) 

The values that can be assigned to W.NOFF depend on the setting of bit 
WS.64B in the window status word (W.NSTS) : 

• If WS.64B = 0, the offset specified in W.NOFF must represent a 
multiple of 256 words (512 bytes) . Because the value of 
W.NOFF is expressed in units of 32-word blocks, the value must 
be a multiple of 8. 

• If WS.64B = 1, the task can align on 32-word boundaries; the 
programmer can therefore specify any offset within the region. 

NOTE 

Applications dependent on 32-word or 
64-byte alignment (WS.64B = 1) may not 
be compatible with future software 
products. Therefore, programmers should 
write applications adaptable to either 
alignment requirement. The bit setting 
of WS.64B could be a parameter chosen at 
assembly time (by means of a prefix 
file) , at task-build time (as input to 
the GBLDEF option) , or at run time (by 
means of command input) . 

FORTRAN Call: 

CALL MAP (iwdb[,ids] ) 
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1 FORTRAN programmers should refer to Section 3.5.2 to determine the 
bit values represented by the symbolic: names described. 
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Iwdb = An 8-word Integer array containing a Window Definition 
Block (see Section 3.5.2.2) 

ids = Directive status 

Macro Call: 

MAP$ wdb 

wdb = Window Definition Block address 

Macro Expansion: 

MAP$ WDB ADR 

.BYTE 121., 2 ;MAP$ MACRO DIC, DPB SIZE=2 WORDS 

.WORD WDBADR ;WDB ADDRESS 

Window Definition Block Parameters: 

Input parameters 

Array ^^f\ 

Element Offset 

iwdb(l) W.NID — ID of the window to be mapped 
bits 0-7 

iwdb(4) W.NRID — ID of the region to which the window is 

to be mapped, or if the task region is 
to be mapped 

iwdb(5) W.NOFF — Offset, in 32-word blocks, within the 

region at which mapping is to begin. ^^^ 
Note that if WS.64B in the window status 
word equals 0, the value specified must 
be a multiple of 8. 

iwdb(6) W.NLEN — Length, in 32-word blocks, within the 

region to be mapped, or if the length 
is to default to either the size of the 
window or the space remaining in the 
region from the specified offset, 
whichever is smaller _ 

iwdb(7) W.NSTS — Bit settingsl in the window status word: ! 

WS.WRT -- 1 if write access is desired 

WS.64B — for 256-word (512-byte) 
alignment, or 1 for 32-worc3 
(64-byte) alignment. 

Output parameters » 

iwdb(6) W.NLEN — Length of the area within the region 

actually mapped by the window 

iwdb(7) W.NSTS — Bit settings^ in the window status word: 

WS.UNM — 1 if the window was unmapped 
first 
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Local Symbol Definitions: 

M.APBA — Window Definition Block address (2) 
DSW Return Codes: 

IS. sue — Successful completion 

lE.PRI — Privilege violation 

lE.NVR — Invalid region ID 

lE.NVW — Invalid address window ID 

lE.ALG — Task specified an invalid region offset and length 
combination in the Window Definition Block 
parameters; or WS.64B = and the value of W.NOFF is 
not a multiple of 8 

lE.ADP — Part of the DPB or WDB is out of the issuing task's 
address space 

lE.SDP — Die or DPB size is Invalid 

lE.HWR — Region had a parity error or a load failure 

IE. ITS — WS.RES was set and region is not resident 

Notes: 

1. When the Map Address Window directive is issued, the task may 
be blocked until the region is loaded. 

2. Bit WS.RES in word W.NSTS of the Window Definition Block, 
when set, specifies map the region only if the region is 
resident. 
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6.3.38 Mark Time 

The Mark Time directive instructs the system to declare a significant 

event after an indicated time interval. The interval begins when the 

task issues the directive; however, task execution continues during ^ 

the interval. If an event flag is specified, the flag is cleared when 

the directive is issued, and set when the significant event occurs. 

If an AST entry point address is specified, an AST (see Section 2.3.3) 

occurs at the time of the significant event. When the AST occurs, the 

task's PS, PC, directive status. Wait For mask words, and the event 

flag number specified in the directive are pushed onto the issuing ' 

task's stack. If neither an event flag number nor an AST service 

entry point is specified, the significant event still occurs after the 

indicated time interval. See Notes below. 

FORTRAN Calls: 

CALL MARK ( ef n , tmg , tnt [ , ids] ) J«% 

efn = Event flag number 

tmg = Time interval magnitude (see Note 5) 

tnt = Time interval unit (see Note 5) 

ids = Directive status 

The ISA standard call for delaying a task for a specified time 

interval is also provided: ^^^ 

CALL WAIT (tmg,tnt[,ids] ) 

tmg = Time interval magnitude (see last Note below) 

tnt = Time interval unit (see last Note below) 

ids = Directive status 
Macro Call: 

MRKT$ [efn] ,tmg,tnt[ ,ast] ' 

efn = Event flag number 

tmg = Time interval magnitude (see last Note below) 

tnt = Time interval unit (see last Note below) 

ast = AST entry point address 

Macro Expansion: 

MRKT$ 52. ,30. ,2,MRKAST 

.BYTE 23., 5 ;MRKT$ MACRO DIC, DPB SIZE=5 WORDS 

.WORD 52, ; EVENT FLAG NUMBER 52. 

.WORD 30. ;TIME MAGNITUDE=30. 

•WORD 2 ;TIME UNIT=SECONDS 

.WORD MRKAST ; ADDRESS OF MARK TIME AST ROUTINE 
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Local Symbol Definitions: 

M.KTEF — Event flag (2) 

M.KTMG — Time magnitude (2) 

M.KTUN — Time unit (2) 

M.KTAE — AST entry point address (2) 
DSW Return Codes: 

For CALL MARK and MRKT$: 

IS. sue — Successful completion 

lE.UPN — Insufficient dynamic memory 

lE.ITI — Invalid time parameter 

lE.IEF — Invalid event flag number (>64 or <0) 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 

lE.SDP — Die or DPB size is invalid 

For CALL WAIT: 

RSX-llM/M-PLUS provides the following positive error codes to be 
returned for ISA calls: 

2 — Insufficient dynamic storage 

3 — Specified task not installed 
94 — Invalid time parameters 

98 — Invalid event flag number 

99 — Part of DPB out of task's range 

100 — Die or DPB size invalid 
Notes: 

1. Mark Time requires dynamic memory for the clock queue entry. 

2. If an AST entry point address is specified, the AST service 
routine is entered with the task's stack in the following 
state: 

SP + 10 - Event flag mask word-'- 
SP-t-06 - PS of task prior to AST 
SP-f04 - PC of task prior to AST 



1 The event flag mask word preserves the Wait For conditions of a 
task prior to AST entry. A task can, after an AST, return to a Wait 
For state. Because these flags and the other stack data are in the 
user task, they can be modified. Such modification is strongly 
discouraged, however, since the task can easily fault on obscure 
conditions. 
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SP+02 - DSW of task prior to AST 
SP+00 - Event flag number or zero (if none was 
specified in the Mark Time directive) 

The event flag number must be removed from the task's stack 
before an AST Service Exit directive (see Section 6.3.4) is 
executed. 

3. If the directive is rejected, the specified event flag is not 
guaranteed to be cleared or set. Consequently, if the task 
indiscriminately executes a Wait For directive and the Mark 
Time directive is rejected, the task may wait indefinitely. 
Care should always be taken to ensure that the directive was 
successfully completed. 

4. If a task issues a Mark Time directive that specifies a 
common event flag and then exits before the indicated time 
has elapsed, the event flag is not set. 

5. The Executive returns the code lE.ITI (or 94) in the 
Directive Status Word if the directive specifies an invalid 
time parameter. The time parameter consists of two 
components: the time interval magnitude and the time 
interval unit, represented by the arguments tmg and tnt 
respectively. 

A legal magnitude value (tmg) is related to the value 
assigned to the time interval unit (tnt) . The unit values 
are encoded as follows: 

For an ISA FORTRAN call (CALL WAIT) : 

= Ticks. A tick occurs for each clock interrupt and 

is dependent on the type of clock installed in the 
system. 

For a line frequency clock, the tick rate is 
either 50 or 60 per second, corresponding to the 
power-line frequency. 

For a programmable clock, a maximum of 1000 ticks 
per second is available (the exact rate is 
determined at system generation time) . 

1 = Milliseconds. The subroutine converts the 

specified magnitude to the equivalent number of 
system clock ticks. 

For all other FORTRAN and macro calls: 

1 = Ticks. See definition of ticks above. 
For both types of FORTRAN calls and all macro calls: 

2 = Seconds 

3 = Minutes 

4 = Hours 



fwBflHSfcj 
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The magnitude (tmg) is the number of units to be clocked. 
The following list describes the magnitude values that are 
valid for each type of unit. In no case can the value of tmg 
exceed 24 hours. The list applies to both FORTRAN and macro 
calls. 

If tnt = 0, 1, or 2, tmg can be any positive value with 
a maximum of 15 bits. 

If tnt = 3, tmg can have a maximum value of 1440(10). 

If tnt = 4, tmg can have a maximum value of 24(10). 
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6.3.39 Queue I/O Request 

The Queue I/O Request directive instructs the system to place an I/O 
request for an indicated physical device unit into a queue of 
priority-ordered requests for that device unit. The physical device 
unit is specified as a logical unit number (LUN) assigned to the 
device. 

The device drivers declare a significant event when the I/O transfer 
completes. If the directive call specifies an event flag, the 
Executive clears the flag when the request is queued and sets the flag 
when the significant event occurs. 

The I/O status block is also cleared v/hen the request is queued and is 
set to the final I/O status when the I/O request is complete. If an 
AST service routine entry point address is specified, the AST occurs 
upon I/O completion, and the task's Wait For mask word, PS, PC, DSW, 
and the address of the I/O status block are pushed onto the task's 
stack . 

The description below deals solely with the Executive directive; the 
device-dependent information can be found in the RSX-llM/M-PLUS I/O 
Drivers Reference Manual , See Notes below. 

FORTRAN Call: 

CALL QIO (fnc,lun, [efn] , [pr i] , [isb] , [prl] [ ,ids] ) 

fnc = I/O function code! 

lun = Logical unit number 

efn = Event flag number 

pri = Priority; ignored, but must be present 

isb = 2-word integer array to receive final I/O status 

prl = 6-word Integer array containing device-dependent 
parameters to be placed in parameter words 1 through 6 
of the DPB. 

ids = Directive status 

Macro Call: 

QIO$ fnc, lun, [efn] , [pri] , [isb] ,, [ast] , [prl] 

fnc = I/O function codel 

lun = Logical unit number 

efn = Event flag number 

pri = Priority; ignored, but must be present 



1 



I/O function code definitions are included in the RSX-llM/M-PLUS 
I/O Drivers Reference Manual . 
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isb 
ast 
prl 
Macro Expansions 



Address of I/O status block 

Address of entry point of AST service routine 

Parameter list of the form <P1,...P6> 



QIO$ 

.BYTE 

.WORD 

.WORD 

.BYTE 

• WORD 

• WORD 
.WORD 
.WORD 
.WORD 

• WORD 
.WORD 
.WORD 



IO.RVB,7,52. , ,IOSTAT,IOAST,<IOBUFR,512.> 



1,12. 

lO.RVB 

7 

52. ,0 

lOSTAT 

lOAST 

lOBUFR 

512. 











QIO$ MACRO Die, DPS SIZE=12 
FUNCTION=READ VIRTUAL BLOCK 
LOGICAL UNIT NUMBER 7 
EFN 52., PRIORITY IGNORED 
ADDRESS OF 2-WORD I/O STATUS BLOCK 
ADDRESS OF I/O AST ROUTINE 
ADDRESS OF DATA BUFFER 
BYTE COUNT=512. 
ADDITIONAL PARAMETERS... 
. ..NOT USED IN. . . 
...THIS PARTICULAR... 
...INVOCATION OF QUEUE I/O 



Local Symbol Definitions: 

Q.IOFN — I/O function code (2) 

Q.IOLU — Logical unit number (2) 

Q.IOEF — Event flag number (1) 

Q.IOPR — Priority (1) 

Q.IOSB — Address of I/O status block (2) 

Q.IOAE — Address of I/O done AST entry point (2) 

Q.IOPL — Parameter list (6 words) (12) 
DSW Return Codes: 

IS. sue — Successful completion 

lE.UPN — Insufficient dynamic memory 

lE.ULN — Unassigned LUN 

lE.HWR — Device driver not loaded 

lE.PRI — Task other than despooler attempted a write logical 
block operation 

lE.ILU — Invalid LUN 

lE.IEF — Invalid event flag number (>64 or <0) 

lE.ADP — Part of the DPB or I/O status block is out of the 
issuing task's address space 



lE.SDP 



Die or DPB size is invalid 
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Notes: 



1. If the directive call specifies an AST entry point address, 
the task enters the AST service routine with its stack in the 
following state: 

SP+10 - Event flag mask word 
SP+06 - PS of task prior to AST 
SP+04 - PC of task prior to AST 
SP+02 - DSW of task prior to AST 

SP+00 - Address of I/O status block, or zero, if none 
was specified in the QIO directive. 

The address of the I/O status block, which is a 

trap-dependent parameter, must be removed from the task's 

stack before an AST Service Exit directive (see Section 
6.3.4) is executed. 

2. If the directive is rejected, the specified event flag is not 
guaranteed to be cleared or set. Consequently, if the task 
indiscriminately executes a Wait For directive and the QIO 
directive is Rejected, the task may wait indefinitely. Care 
should always be taken to ensure that the directive was 
successfully completed. 

3. Tasks cannot be checkpointed with QIO outstanding for two 
reasons: 

a. If the QIO directive results in a data transfer, the data 
transfers directly to or from the user-specified buffer. 

b. If an I/O status block address is specified, the 
directive status is returned directly to the I/O status 
block . 

The Executive waits until a task has no outstanding I/O 
before initiating checkpointing in all cases except the one 
described below. 

In systems that support the checkpointing of tasks during 
terminal input, the terminal driver checks for the following 
conditions when the driver dequeues an input request for a 
task: 

• That the task is checkpointable 

• That checkpointing is enabled 

• That the task is not executing an AST routine 

If the three conditions exist, the Executive immediately 
stops the task's execution. Any competing task waiting to be 
loaded into the partition can checkpoint the stopped task, 
regardless of priority. If the stopped task is checkpointed, 
the Executive does not bring it back into memory until its 
terminal input has completed.. While the task is stopped, the 
terminal driver buffers the task's terminal input. 

4. A privileged task that is linked to a common (read-only) area 
can issue QIO write requests to that area. 



.'^^^wli 



6-92 



DIRECTIVE DESCRIPTIONS 



QIOW$ 



6.3.40 Queue I/O Request And Wait 

The Queue I/O Request And Wait directive is identical to Queue I/O 
Request in all but one aspect. If the Wait variation of the directive 
specifies an event flag, the Executive automatically effects a Wait 
For Single Event Flag directive. If an event flag is not specified, 
however, the Executive treats the directive as if it were a simple 
Queue I/O Request. 

The following description lists the FORTRAN and macro calls with the 
associated parameters, as well as the macro expansion. Consult the 
description of Queue I/O Request for a definition of the parameters, 
the local symbol definitions, the DSW return codes, and explanatory 
notes. 

FORTRAN Call: 

CALL WTQIO (fnc,lun, [efn] , [pri] , [isb] , [prl] [,ids] ) 

fnc == I/O function codel 

lun := Logical unit number 

efn == Event flag number 

pri = Priority; ignored, but must be present 

isb = 2-word integer array to receive final I/O status 

prl = 6-word integer array containing device-dependent 
parameters to be placed in parameter words 1 through 6 
of the DPB 

ids = Directive status 

Macro Call: 

QIOW$ fnc,lun,efn, [pri] ,[isb] ,[ast] [,prl] 

fnc = I/O function codel 

lun = Logical unit number 

efn = Event flag number 

pri = Priority; ignored, but must be present 

isb = Address of I/O status block 

ast = Address of entry point of AST service routine 

prl = Parameter list of the form <P1,...P6> 



1 I/O function codes are defined in the RSX-llM/M-PLUS I/O Drivers 
Reference Manual. 



6-93 



DIRECTIVE DESCRIPTIONS 



Macro Expansion; 



QIOW$ 


lO.RVB 


.BYTE 


3,12. 


.WORD 


lO.RVB 


• WORD 


7 


.BYTE 


52. ,0 


.WORD 


lOSTAT 


.WORD 


I OAST 


.WORD 


lOBUFR 


.WORD 


512. 


.WORD 





• WORD 





.WORD 





.WORD 






IO.RVB,7,52., ,IOSTAT,I0AST,<I0BUFR,512.> 

QIO$ MACRO Die, DPB SIZE=12. 
FUNCTION=READ VIRTUAL BLOCK 
LOGICAL, UNIT NUMBER 7 
EFN 52., PRIORITY IGNORED 
ADDRESS OF 2-WORD I/O STATUS BLOCK 
ADDRESS OF I/O AST ROUTINE 
ADDRESS OF DATA BUFFER 
BYTE COUNT=512. 
ADDITIONAL PARAMETERS... 
. . .NOT USED IN. . . 
...THIS PARTICULAR... 
...INVOCATION OF QUEUE I/O 
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6.3.41 Receive Data Or Stop 

The Receive Data Or Stop directive attempts to dequeue a Send Data 
packet from the specified task (or any task). If there isno such 
packet to be dequeued, the issuing task is stopped. In this case 
another task, the sender task, is expected to issue an Unstop 
directive after sending data. On successful return from this 
directive, a directive status of IS.SUC indicates that a packet has 
been received. A status of IS. SET indicates that the task was stopped 
and has been unstopped. The directive must then be reissued to 
retrieve the packet. 

FORTRAN Call: 

CALL RCST ( [rtname] ,ibuf , [ids] ) 

rtnarae = Name of task from which data is to be received 

ibuf = Address of 15-word buffer to receive the sender task 
name and data 

ids = Integer to receive the directive status word 

Macro Call: 

RCST$ [tname] ,buf 

tname = Name of task from which data is to be received — If 
not specified, data may be received from any task 

buf = Address of 15-word buffer to receive the sender task 
name and data 

Macro Expansion: 

LPHA.TSKBUF 

RCST$ MACRO DIG, DPB SIZE=4 WORDS 
DATA SENDER TASK NAME 
BUFFER ADDRESS 

Local Symbol Definitions: 

R.CSTN — Task name (4) 

R.CSBF — Buffer address (2) 
DSW Return Codes: 

IS.SUC — Successful completion 

IS. SET — No data was received and task was stopped (note that 
the task must be Unstopped before it can see this 
status) 

IE. AST — The issuing task is at AST state 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 

lE.SDP — Die or DPB size is invalid 
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ALPHA, TSKBUF 


.BYTE 


139., 4 


.RAD50 


ALPHA 


.WORD 


TSKBUF ; 
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Note: 



In RSX-llM-PLUS systems that support variable send and receive 
directives (secondary pool support SYSGEN option) , the Receive 
Data Or Stop directive is treated as a 13. word Variable Receive 
Data Or Stop directive (see Section 6.3.73). 



^f*P*WB5L 
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6.3.4 2 Receive Data 

The Receive Data directive instructs the system to dequeue a 13-word 
data block for the issuing task; the data block has been queued 
(FIFO) for the task via a Send Data Directive. 

A 2-word sender task name (in Radix-50 form) and the 13-word data 
block are returned in an indicated 15-word buffer, with the task name 
in the first two words. 

In a system that supports multiuser protection, a task can be 
installed as a slave by the keyword /SLV=YES (see the RSX-llM/M-PLUS 
MCR Operati o ns Manual ). When a slave task issues the Receive Data 
dTrective, it assumes the UIC and TI: terminal of the task that sent 
the data. 

FORTRAN Calls 

CALL RECEIV ( [ tsk] ,buf [ , , ids] ) 

tsk. == Sender task name 

15-word integer array for received data 

Directive status 



buf 
ids 
Macro Call: 
RCVD$ 
tsk 
buf 



[tsk] ,buf 

Sender task name 

Address of 15-word buffer 



RCVD$ 


ALPHA, DATBUF 


.BYTE 


75. ,4 


.RAD50 


/ALPHA/ 


.WORD 


DATBUF 



Macro Expansion: 

TASK NAME AND BUFFER ADDRESS 
RCVD$ MACRO DIC, DPB SIZE=4 WORDS 
SENDER TASK NAME 
ADDRESS OF 15. -WORD BUFFER 

Local Symbol Definitions: 

R.VDTN — Sender task name (4) 

R.VDBA — Buffer address (2) 
DSW Return Codes: 

IS. sue — Successful completion 

IE. ITS — No data currently queued 

lE.ADP — Part of the DPB or buffer is out of the issuing 
task's address space 



lE.SDP — DIC or DPB size is invalid 
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Note: 



In RSX-llM-PLUS systems that support variable send and receive 
directives (secondary pool support SYSGEM option) , the Receive 
Data directive is treated as a 1].. word Variable Receive Data 
directive (see Section 6.3.72). 
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6.3.43 Receive Data Or Exit 

The Receive Data Or Exit directive instructs the system to dequeue a 
13-word data block for the issuing task; the data block has been 
queued (FIFO) for the task via a Send Data directive. 

A 2-word sender task name (in Radix-50 form) and the 13-word data 
block are returned in an indicated 15-word buffer, with the task name 
in the first two words. 

If no data has been sent, a task exit occurs. To prevent the possible 
loss of Send packets, the user should not rely on I/O rundown to take 
care of any outstanding I/O or open files; the task should assume 
this responsibility. 

In a system that supports multiuser protection, a task can be 
installed as a slave by the keyword /SLV=YES (see the RSX-llM/M-PLUS 
MCR Operations Manual ) . When a slave task issues the Receive Data Or 
Exit directive, it assumes the UIC and TI: terminal of the task that 
sent the data. See Notes below. 

FORTRAN Call: 

CALL RECOEX ( [ tsk] , buf [ , , ids] ) 

tsk = Sender task name 

buf = 15-word integer array for received data 

ids = Directive status 



Macro Call: 
RCVX$ 



[tsk] ,buf 



tsk = Sender task name 



buf = Address of 15-word buffer 



Macro Expansion: 



RCVX$ 


ALPHA, DATBUF 


. BYTE 


77. ,4 


.RAD 50 


/ALPHA/ 


.WORD 


DATBUF 



TASK NAME AND BUFFER ADDRESS 
RCVX$ MACRO Die, DPB SIZE=4 WORDS 
SENDER TASK NAME 
ADDRESS OF 15. -WORD BUFFER 



Local Symbol Definitions: 

R.VXTN = Sender task name (4) 
R.VXBA = Buffer address (2) 

DSW Return Codes: 

IS. sue — Successful completion 

lE.ADP — Part of the DPB or buffer is out of the issuing 
task's address space 

lE.SDP — Die or DPB size is invalid 
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Notes: 



1. A FORTRAN program that issues the RECOEX call must first 
close all files by issuing CLOSE calls. See the IAS/RSX-11 
FORTRAN IV or the FORTRAN IV-PLUS User's Guide for 
instructions concerning how to ensure that such files are 
closed properly if the task exits. 

To avoid the time overhead involved in the closing and 
reopening of files, the task should first issue the RECEIV 
call. If the directive status indicates that no data were 
received, then the task can close all files and issue the 
call to RECOEX. 

2. If no data have been sent, that is, if no Send Data directive 
has been issued, the task exits. Send packets may be lost if 
a task exits with outstanding I/O or open files (see third 
paragraph of this section) . 

3. The Receive Data Or Exit directive is useful in avoiding a 
possible race condition that can occur between two tasks 
communicating via the Send and Receive directives. The race 
condition occurs when one task executes a Receive directive 
and finds its receive queue empty; but before the task can 
exit, the other task sends it a message. The message is lost 
because the Executive flushes the receiver task's receive 
queue when it exits. This condition can be avoided by the 
receiving task's executing a Receive Data Or Exit directive. 
If the receive queue is found to be empty, a task exit occurs 
before the other task can send any data; thus, no loss of 
data can occur. 

4. On Exit, the Executive frees task resources. In particular, 
the Executive: 

• Detaches all attached devices 

• Flushes the AST queue 

• Flushes the receive and receive-by-reference queues 

• Flushes the clock queue for outstanding Mark Time 
requests for the task «. 

• Closes all open files (files open for write access are 
locked) 

• Detaches all attached regions except in the case of a 
fixed task, where no detaching occurs 

• Runs down the task's I/O 

• Frees the task's memory if the exiting task was not 
fixed 

• In RSX-llM-PLUS systems, marks all virtual terminal 
units the task has created for deallocation 

• Disconnects all connected tasks 

5. If the task exits, the Executive declares a significant 
event. 



i^^^ 
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6. In RSX-ILM-PLUS systems tliat support variable send and 
receive directives (secondary pool support SYSGEN option) , 
the Receive Data Or Exit directive is treated as a 13. word 
Variable :^eceive Data Or Exit directive (see Section 6.3.74). 
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RDAF$ 



6.3.44 Read All Event Flags 

The Read All Event Flags directive instructs the system to read all 64 
event flags for the issuing task and record their polarity in a 64-bit 
(4-word) buffer. 



NOTE 

Group-globl event flags (event flags 
65 - 96) are not returned by this 
directive. 



FORTRAN Call: 

Only one event flag can be read by a FORTRAN task. The call is: 
CALL READEF (efn,ids) 

efn = Event flag number 

ids = Directive status 

The Executive returns the status codes IS. SET (+02) and IS.CLR 
(00) for FORTRAN calls to report event flag polarity. 

Macro Call: 

RDAF$ buf 
Buffer Format: 

word — Task Local Flags 1-161 

word 1 — Task Local Flags 17-32 

word 2 — Task Common Flags 33-48 

word 3 — Task Common Flags 49-64 

Macro Expansion: 

LGBUF 

;RDAF$ MACRO DIG, DPS SIZE=2 WORDS 
/ADDRESS OF 4-WORD BUFFER 

Local Symbol Definitions: 

R.DABA — Buffer address (2) 
DSW Return Codes: 

IS.SUC — Successful completion 

lE.ADP — Part of the DPB or buffer is out of the issuing 
task's address space 



RDAF$ 


FLGBUF 


.BYTE 


39. ,2 


.WORD 


FLGBUF 



lE.SDP — 



DIG or DPB size is invalid 



^^■^^fc 
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RDXF$ 



6.3.45 Read Extended Event Flags 

The Read Extended Event Flags directive instructs the system to read 
all local, common, and group-global event flags for the issuing task 
and record their polarity in a 64-bit (6-word) buffer. 

FORTRAN Call: 

Only one event flag can be read by a FORTRAN task. The call is: 

CALL READEF (efn[,ids]) 

efn == Event flag number 

ids == Directive status 

The Executive returns the status codes IS. SET (+02) and IS.CLR 
(00) for FORTRAN calls to report event flag polarity. 



Macro Call 




RDXF$ 


buf 


Buffer- Format: 


word 


— 


word 


1 — 


word 


2 — 


word 


3 — 


word 


4 — 


word 


5 — 



Task Local Flags 1-16 
Task Local Flags 17-32 
Task Common Flags 33-48 
Task Common Flags 49-64 
Task Group-Global Flags 65-80 
— Task Group-Global Flags 81-96 
Macro Expansion: 



RDXF$ 


FLGBUF 


• BYTE 


39. ,3 


.WORD 


FLGBUF 



;RDXF$ MACRO DIC, DPB SIZE=3 WORDS 
; ADDRESS OF 6-WORD BUFFER 

Local Symbol Definitions: 

R.DABA — Buffer address (2) 
DSW Return Codes: 

IS. sue — Successful completion 

IS.CLR — Group-global event flags do not exist.. Words 4 and 5 
of the buffer contain 

lE.ADP — part of the DPB or buffer is out of the issuing 
task's address space 

lE.SDP — DIC or DPB size is invalid 
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RMAFSS 

6.3.46 Remove Affinity^";:'/'-.- ■,;/•.'-;,■-■;,-.'.; .'•/ 

The Remove Affinity di rifectlve; removes' ftfte task's CPU affinity that was 
previously established ;by' Issuing ^aSeti: Affinity directive. Note that 
only the $S form is available :for this di rective. 

FORTRAN Call : 

CALL RMAF ([ids]) 'v "'-.:' /i' ^'■■- ^i ::■"■ ':^ 

ids = Integer ■ to rebel ve Die tf^ Status Word 
Macro Call: 

RMAF$ S !:'-V'^''li::-:- ^-■'■: -^jTiV"^ 

Macro Expansion: 

■ ;PUSH DE'B.ONTO THt: STACK 
:'>RMAE$S\ MACRO DIG, DPB SIZE = 1 WORD 
;,iTRAf, TO EXECUTIVE 

Local S ymbo 1 De f i n i t i on?: ;'■;:;:;, •; :;;:]■;?,:■;?'; 

None ! i'; .';.' 

DSW Return Codes: 

IS. sue — Succesiifui completion 

lE.ADP — Part dl^tihe DBB-iJiS Quft of the issuing task's address 

space 'y^^-^:'?"--''' -''':"' ' ■■•^^'; 

IE.3DP — Die or :DEB: ijslzevis; ifivalid 
IE. ITS — Task install^d>;witji:, affinity 



RMAF$ S 




MOV 


(PC) + ,-(:SP:) 


.BVTE 


163.,1 V> 


EMT 


377 



Note: 



A task that is inst^iled W task; affinity must not issue this 
directive. Any attempt to do ; so results in an IE. ITS error 

returned. iK-'^H;:H;'>i---i-'^;.\,' "\:,--!'-''vi 
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RQST$ 



6.3.47 Request Task 

The Request Task directive instructs the system to activate a task. 
The task is activated and subsequently runs contingent upon priority 
and memory availability. Request is the basic mechanism used by 
running tasks to initiate other installed (dormant) tasks. Request is 
a frequently used subset of the Run directive. See Notes below. 

FORTRAN Call: 

CALL REQUES { tsk , [opt] [ , ids] ) 

tsk = Task name 

opt = 4-word integer array 



opt(l) = partition name first half; 
must be present 

opt (2) = partition name second half; 
must be present 



ignored, but 
ignored, but 



ids 

Macro Call 

RQST$ 



opt(3) = priority; ignored, but must be present 
opt(4) = User Identification Code 
Directive status 



tsk , [prt] , [pri] [ ,ugc,umc] 
tsk = Task name 

prt = Partition name; ignored, but must be present 
pri = Priority; ignored, but must be present 
ugc = U.TC group code 
umc = UIC member code 
Macro Expansion: 



RQST$ MACRO DIG, DPB SIZE=7 WORDS 

TASK "ALPHA" 

PARTITION IGNORED 

PRIORITY IGNORED 

UIC UNDER WHICH TO RUN TASK 



RQST$ 


ALPHA, ,,20,10 


.BYTE 


1 1 . , 7 


.RAD50 


/ALPHA/ 


.WORD 


0,0 


.WORD 





• BYTE 


10,20 



Local Symbol Definitions: 

R.QSTN — Task name (4) 

R.QSPN — Partition name (4) 

R.QSPR — Priority (2) 
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R.QSGC — UIC group (1) 

R.QSPC — UIC member (1) ^%s 

DSW Return Codes: 

IS. sue — Successful completion 

lE.UPN — Insufficient dynamic memory ^ 

IE. INS — Task is not installed 

IE. ACT — Task is already active 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 

IE. SOP — Die or DPB size is invalid 
Notes: 

1. The requested task must be installed in the system. ^tHk, 

2. If the partition in which a requested task is to run is 
already occupied, the Executive places the task in a queue of 
tasks waiting for that partition. The requested task then 
runs, depending on priority, and resource availability, when 
the partition is free. Another possibility is that 
checkpointing may occur. If the current occupant(s) of the 
partition is checkpointable, has checkpointing enabled, and 
is of lower priority than the requested task, it is written 
to disk when its current outstanding I/O completes; the 
requested task is then read into the partition. 0tfk^ 

3. Successful completion means that the task has been declared 
active, not that the task is actually running. 

4. The requested task acquires the same TI : terminal assignment 
as that of the requesting task. 

5. The requested task always runs at the priority specified in 
its task header. 

6. A task that executes in a system-controlled partition i^!ll| 
requires dynamic memory 'for the partition control block used 

to describe its memory requirements. 

7. In a system that does not support multiuser protection, a 
task can be requested under any UIC, regardless of the UIC of 
the requesting task. If no UIC is specified in the request, 
the system uses the UIC from the task's header, which was 
specified at task-build time. 

8. In a system that supports multiuser protection, each active 
task has two UICs — a protection UIC and a default UIC. 
These are both returned when a task issues a Get Task 
Parameters directive (GTSK$) . The UICs are used in the 
following ways: r 

a. The protection UIC determines the task's access rights 
for opening files and attaching to regions. When a task 
attempts to open a file, the system compares the task's 
protection UIC against the protection mask of the ^tK^ 
specified UFD; the comparison determines whether the ^^" 
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task is to be considered for system, owner, group, or 
world access. 

b. The default UIC is used by the File Control Subroutines 
(FCS) to determine the default UFD when a file-open 
operation does not specify a UIC. (The default UIC has 
no significance when a task attaches to a region.) 

In a multiuser protection system, each terminal also has a 
protection UIC and a default UIC. If a terminal is 
nonpr ivileged, the protection UIC is the log-on UIC, and the 
default UIC is the UIC specified in the last SET /UIC command 
issued. If no SET /UIC command has been issued, the default 
UIC is equal to the log-on UIC. If the terminal is 
privileged, both the protection and the default UICs are 
equal either to the UIC specified in the last SET /UIC 
command or to the log-on UIC if a SET /UIC command has not 
been issued. 

The system establishes a task's UICs when the task is 
activated. In general, when the MCR Dispatcher or the MCR 
Run command activates a task, the task assumes the protection 
and default UICs of the issuing terminal. However, if the 
user specifies the /UIC keyword to the MCR Install or Run 
command, the specified UIC becomes the default UIC for the 
activated task; and if the issuing terminal is privileged, 
the specified UIC becomes the activated task's protection UIC 
as well. 

The system establishes UICs in the same manner when one task 
issues a Request directive to activate another task. The 
protection and default UICs of the issuing task generally 
become the corresponding UICs of the requested task. 
However, if a nonpr ivileged task specifies a UIC in a Request 
directive, the specified UIC becomes only the default UIC for 
the requested task. If a privileged task specifies a UIC in 
a Request directive, the specified UIC becomes both the 
protection and default UIC for the requested task. 
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RREF$ 



j^^^%. 



6.3.48 Receive By Reference 

The Receive By Reference directive requests the Executive to dequeue 
the nej^t packet in the receive-by-reference queue of the issuing 
(receiver) task. Optionally, the task will exit if there are no 
packets in the queue. The directive may also specify that the 
Executive proceed to map the region referred to. 

If successful, the directive declares a significant event. 

Each reference in the task's receive-by-reference queue represents a 
separate attachment to a region. if a task has multiple references to 
a given region, it is attached to that region the corresponding number 
of times. Because region attachment requires system dynamic memory, 
the receiver task should detach from any region that it was already 
attached to in order to prevent depletion of the memory pool. That 
is, the task needs to be attached to a given region only once. 

If the Executive does not find a packet in the queue, and the task has 
set WS.RCX in the window status word (W.NSTS) , the task exits. If 
WS.RCX is not set, the Executive returns the DSW code IE. ITS. 

If the Executive finds a packet, it writes the information provided to 
the corresponding words in the Window Definition Block. This 
information provides sufficient information to map the reference, 
according to the sender task's specifications, with a previously 
created address window. 

If the address of a 10-word receive buffer has been specified (W.NSRB 
in the Window Definition Block) , then the sender task name and the 
eight additional words passed by the sender task (if any) are placed 
in the specified buffer. If the sender task did not pass on any 
additional information, the Executive writes in the sender task name 
and eight words of zero. 



^ffB^^ik 



-f'^^Sii 



If the WS.MAP bit in the window status word has been set to 1, the 
Executive transfers control to the Map Address Window directive (see 
Section 6.3.37) to attempt to map the reference. 

When a task that has unreceived packets in its receive-by-reference 
queue exits or is removed, the Executive removes the packets from the 
queue and deallocates them. Any related flags are not set. 

FORTRAN Call: 

CALL RREF ( iwdb, [ isrb] [ , ids] ) 

iwdb = An 8-word integer array containing a Window Definition 
Block (see Section 3.5.2.2) 

isrb = A 10-word integer array to be used as the receive 
buffer. If the call omits this parameter, the 
contents of iwdb(8) are unchanged. 

ids = Directive status 

Macro Call: 

RREF$ wdb 

wdb = Window Definition Block address 
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Macro Expansion: 



RREF$ 


WDBADR 


.BYTE 


81. ,2 


.WORD 


WDBADR 



;RREF$ MACRO DIG, DPB SIZE=2 WORDS 
;WDB ADDRESS 

Window Definition Block Parameters: 

Inp ut param e ters 

Array 

Element Offset 

iwdb(l) 
bits 0-7 W.NID — ID of an existing window if region is to be 

mapped 

iwdb(7) W.MSTS — Bit settings^ in the window status word: 

WS.MAP — 1 if received reference is to 
be mapped 

WS.RCX — 1 if task exit desired when no 
packet is found in the queue 

iwdb(8) W.NSRB — Optional address of a 10-word buffer, to 

contain the sender task name and additional 
information 

Output par am eters 

iwbd{4) W.NRID — Region ID (pointer to attachment 

description) 

iwdb(5) W.NOFF — Offset word specified by sender task 

iwdb(6) W.NLEN — Length word specified by sender task 

iwdb(7) W.NSTS — Bit settingsl in the window status word: 

WS.RED — 1 if attached with read access 

WS.WRT — 1 if attached with write access 

WS.EXT — 1 if attached with extend 
access 

WS.DEL — 1 if attached with delete 
access 

WS.RRF — 1 if receive was successful 

The Executive clears the remaining bits. 

Local Symbol Definitions: 

R.REBA — Window definition block address (2) 



1 FORTRAN programmers should refer to Section 3.5.2 to determine the 
bit values represented by the symbolic names described. 
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DSW Return Codes: 

IS. sue — Successful completion "^p 

IS.HWR — Region has incurred a parity error 

IE. ITS — No packet found in the receive-by-reference queue 

lE.ADP — Address check of the DPB, WDB, or the receive buffer v 

(W.NSRB) failed 

lE.SDP — DIG or DPB size is invalid 



1^^^ 



-f^l^T^ 



.^■i^ 
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RSUM$ 

6.3.49 Resume Task 

The Resume Task directive instructs the system to resume the execution 
of a task that has issued a Suspend directive. 

FORTRAN Call: 

CALL RESUME (tsk[,ids]) 

tsk = Task name 

ids = Directive status 

Macro Call: 

RSUM$ tsk 

tsk = Task name 

Macro Expansion: 

RSUM$ ALPHA 

.BYTE 47., 3 ; RSUM$ MACRO DIC, DPB SIZE=3 WORDS 

.RAD50 /ALPHA/ ; TASK "ALPHA" 

Local Symbol Definitions: 

R.SUTN — Task name (4) 
DSW Return Codes: 

IS. sue — Successful completion 

IE. INS — Task is not installed 

IE. ACT — Task is not active 

IE. ITS — Task is not suspended 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 

lE.SDP — DIC or DPB size is invalid 
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RUN$ 

6.3.50 Run Task 

The Run Task directive causes a task to be requested at a specified 
future time, and optionally to be requested periodically. The 
schedule time is specified in terms of delta time from issuance. If 
the smg, rmg, and rnt parameters are omitted. Run is the same as 
Request except that: 

1. Run causes the task to become active one clock tick after the 
directive is issued 

2. The system always sets the TI : device for the requested 
task, to CO: 

See Notes below. 

FORTRAN Call: 

CALL RUN (tsk, [opt] , [smg] ,snt, [rmg] , [rnt] [,ids] ) 
tsk = Task name 
opt = 4-word integer array 

opt(l) = partition name first half; ignored, but 
must be present 

opt (2) = partition name second half; ignored, 
but must be present 

opt (3) = priority; ignored, but must be present 
opt(4) = User Identification Code 
smg = Schedule delta magnitude 

snt = Schedule delta unit (either 1, 2, 3, or 4) 
rmg = Reschedule interval magnitude 
rnt = Reschedule interval unit 
ids = Directive status 
The ISA standard call for initiating a task is also provided: 
CALL START{tsk,smg,snt[,ids] ) 
tsk = Task name 
smg = Schedule delta magnitude 

snt = Schedule delta unit (either 0, 1, 2, 3, or 4) 
ids = Directive status 
Macro Call: 

RUN$ tsk, [prt] , [pri] , [ugc] , [umc] , [smg] , snt [, rmg, rnt] 
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RUN$ 


ALPHA,, 


BYTE 


17. ,11. 


.RAD50 


/ALPHA/ 


.WORD 


0,0 


.WORD 





.BYTE 


10,20 


.WORD 


20. 


.WORD 


3 


.WORD 


10. 


.WORD 


3 
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tsk = Task name 

prt = Partition name; ignored, but must be present 

pri = Priority; ignored, but must be present 

ugc = UIC group code 

umc = UIC member code 

smg = Schedule delta magnitude 

snt = Schedule delta unit (either 1, 2, 3, or 4) 

rmg = Reschedule interval magnitude 

rnt = Reschedule interval unit 

Macro Expansion: 

.PHA,, ,20, 10, 20., 3, 10., 3 

RUN$ MACRO Die, DPB SIZE=11. WORDS 

TASK "ALPHA" 

PARTITION IGNORED 

PRIORITY IGNORED 

UIC TO RUN TASK UNDER 

SCHEDULE MAGNITUDE=20 

SCH. DELTA TIME UNIT=MINUTE (=3) 

RESCH. INTERVAL MAGNITUDE=10 . 

RESCH. INTERVAL UNIT=MINUTE (=3) 

Local Symbol Definitions: 

R.UNTN — Task name (4) 

R.UNPN — Partition name (4) 

R.UNPR — Priority (2) 

R.UNGC — UIC group code (1) 

R.UNPC — UIC member code (1)- 

R.UNSM — Schedule magnitude (2) 

R.UNSU — Schedule unit (2) 

R.UNRM — Reschedule magnitude (2) 

R.UNRU — Reschedule unit (2) 
DSW Return Codes: 

For CALL RUN and RUN$: 

IS. sue — Successful completion 

lE.UPN — Insufficient dynamic memory 

IE. ACT — Multiuser task name specified 

IE. INS — Task is not installed 

IE. PRI — Nonprivileged task specified a UIC other than its own 
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lE.ITI — Invalid time parameter 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 

lE.SDP — DIG or DPB size is invalid 

For CALL START: 

RSX-llM/M-PLUS provides the following positive error codes to be 

returned for ISA calls: 

2 — Insufficient dynamic storage 

3 — Specified task not installed 
94 — Invalid time parameter 

98 — Invalid event flag number 

99 — Part of DPB out of task's address space 

100 — DIG or DPB size invalid 



Notes: 



1. In a multiuser protection system, a nonpr ivileged task cannot 
specify a UIC that is not equal to its own protection UIG. 
(See the Note 8, Section 6.3.47, for a definition of the 
protection UIC.) A privileged task can specify any UIG. 

2. In a system that does not support multiuser protection, a 
task may be run under any UIC, regardless of the UIC of the 
requesting task. If no UIC is specified in the request, the 
Executive uses the default UIC from the requested task's 
header. The priority is always that specified in the 
requested task's Task Control Block. 

3. The target task must be installed in the system. 

4. If there is not enough room in the partition in which a 
requested task is to run, the Executive places the task in a 
queue of tasks waiting for that partition. The requested 
task will then run, depending on priority and resource 
availability, when the partition is free. Another 
possibility is that checkpointing will occur. If the current 
occupant(s) of the partition is checkpointable, has 
checkpointing enabled, is of lower priority than the 
requested task, or is stopped for terminal input, it will be 
written to disk when its current outstanding I/O completes. 
The requested task will then be read into the partition. 

5. Successful completion means the task has been made active; 
it does not mean that the task is actually running. 

6. Time Intervals 

The Executive returns the code lE.ITI in the DSW if the 

directive specifies an invalid time parameter. A time 

parameter consists of two components: the time interval 
magnitude and the time interval unit. 
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A legal magnitude value (smg or rmg) is related to the value 
assigned to the time interval unit snt or rnt. The unit 
values are encoded as follows: 

For an ISA FORTRAN call (CALL START) : 

= Ticks — A tick occurs for each clock interrupt 

and is dependent on the type of clock installed in 
the system. 

For a line frequency clock, the tick rate is 
either 50 or 60 per second, corresponding to the 
power-line frequency. 

For a programmable clock, a maximum of 1000 ticks 
per second is available (the exact rate is 
determined during system generation) . 

1 = Milliseconds — The subroutine converts the 

specified magnitude to the equivalent number of 
system clock ticks. 

For all other FORTRAN and all macro calls: 

1 = Ticks — See definition of ticks above. 
For both types of FORTRAN calls and all macro calls: 

2 = Seconds 

3 = Minutes 

4 = Hours 

The magnitude is the number of units to be clocked. The 
following list describes the magnitude values that are valid 
for each type of unit. In no case can the magnitude exceed 
24 hours. The list applies to both FORTRAN and macro calls. 

If unit = 0, 1, or 2, the magnitude can be any positive 
value with a maximum of 15 bits. 

If unit = 3, the magnitude can have a maximum value of 
1440(10) . 

If unit = 4, the magnitude can have a maximum value of 
24 (10) . 

The schedule delta time is the difference in time from the 
issuance of the RUN$ directive to the time the task is to be 
run. This time may be specified in the range from one clock 
tick to 24 hours. 

The reschedule interval is the difference in time from task 
initiation to the time the task is to be reinitiated. If 
this time interval elapses and the task is still active, no 
reinitiation request will be issued. However, a new 
reschedule interval will be started. The Executive will 
continually try to start a task, wait for the specified time 
interval, and then restart the task. This process continues 
until a CSRQ$ (Cancel Time Based Initiation Requests) 
directive or an MCR Cancel command is issued. 
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9. Run requires dynamic memory for the clock queue entry used to 
start the task after the specified delta time. If the task 
is to run in a system-controlled partition, further dynamic 
memory is required for the task's dynamically allocated 
partition control block (PCB) . 

10. If optional rescheduling is not desired, then the macro call 
should omit the arguments rmg and rnt. 



6-116 



DIRECTIVE DESCRIPTIONS 



SCAL$S 



6.3.51 Supervisor Call 

The Supervisor Call directive is issued by a task in User mode or 
Supervisor mode to call a Supervisor mode library routine. A return 
to the User mode from Supervisor mode routines entered via the SCAL$S 
directive (Macro ;:orm) is via a completion routine that is executed in 
Supervisor mode. Note that only the $S for is available for this 
directive. 

FORTRAN Call: 

Not Supported 
Macro Call: 

SCALSS saddr,caddr 

sacdr = Address of the called Supervisor mode routine 

caddr = Address of the completion routine for return to the 
caller 



Macro Expansion: 

SCALSS 
MOV 



MOV 

MOV 

.BYTE 

DIRS 



a..pha,sup:^tn 
suprtn,-(sp) 

ALPHA,- (SP) 

(?C)+,-(SP) 
1S5. ,3 



;PUSH ADDRESS OF COMPLETION RUUTINC 

;ON-TO STACK 

;PUSH ADDRESS OF CALLED ROUTINE ONTO 

; STACK 

;PUSH Die AND DPB SIZE WORD ONTO STACK 

;SCAL$S MACRO DIG, DPB SIZE=3 WORDS 



Local Symbol Definitions: 

None 
DSW Return Codes: 

IS. sue — Successful completion 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 



lE.SDP — Die or DPB size invalid 



Note: 



This directive transfers control to the specified routine in 
Supervisor mode with all registers preserved and with the 
following stack: 

Supervisor Stack Pointer »- 



Compl 


etion 


routine 


address 


pe+2 


of Supervisor 


Call 


PS of 


Supervisor Call 



User Stack Painter 
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The stack, as shown, represents the stack content immediately 
after issuing the Supervisor Call directive. The User stack 
pointer is r,ot guaranteed to remain valid. 

The Supervisor stack is the User s.tack with three words pushed 

onto it. It is mapped in Supervisor Data Space along with the 

rest of the User mode napping. Previous node bits are set to the 

caller's mode. This is normally User mode, but it may be 
Supervisor mode. 

If there is insufficient stack spcce for the three words, the 
issuing task is aborted. 
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SDAT$ 



6.3.52 Send Data 

The Send Data directive instructs the system to declare a significant 
event and to queue (FIFO) a 13-word block of data for a task to 
receive When a local event flag is specified, the indicated event 
flag is set for the sending task; a significant event is always 
declared. 

FORTRAN Call: 

CALL SEND ( tsk , buf , [ef n] [ , ids ] ) 

tsk = Task name 

buf == 13-word integer array of data to be sent 

efn == Event flag number 

ids = Directive status 

Macro Call: 

SDAT$ tsk, buf [, efn] 

tsk = Task name 

buf = Address of 13-word data buffer 

efn •= Event flag number 

Macro Expansion: 

SDAT$ ALPHA, DATBUF, 52. 



.BYTE 71., 5 

.RAD5 /ALPHA/ 

.WORD DATBUF 

•WORD 52. 



SDAT$ MACRO DIC, DPB SIZE=5 WORDS 
RECEIVER TASK NAME 
ADDRESS OF 13. -WORD BUFFER 
EVENT FLAG NUMBER 52. 



Local Symbol Definitions: 

S.DATN — Task name (4) 

S.DABA — Buffer address (2) 

S.DAEF -- Event flag number (2) 
DSW Return Codes: 

IS. sue -- Successful completion 

IE. INS — Receiver task is not installed 

lE.UPN — Isufficient dynamic memory 

lE.IEF — Invalid event flag number (>64 or <0) 

lE.ADP — Part of the DPB or data block is out of the issuing 
task's address space 

lE.SDP — DIC or DPB size is invalid 
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Notes: 

1. Send Data requires dynamic memory. 

2. If the directive specifies a local event flag, the flag is 
local to the sender (issuing) task. RSX-llM does not allow 
one task to set or clear a flag that is local to another 
task, 

3. In j^SX-llM-PLUS systems that support variable send and 
receive directiviss (secondary pool; support SYSGEN option), 
the Send Data directive is treated as ai 13. word Variable 
Send Data di recti ve ( see Section 6,3*75) . 
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6.3.53 Send, Request and Connect 

The Send, Request And Connect directive performs a Send Data to the 
specified task. Requests the task if it is not already active, and 
then Connects to the task. The receiver task normally returns status 
via an Enit Status or Exit With status directive. 

FORTRAN Call: 

CALL SD^C (rtnarae, ibuf , [iefn] , [ iast] , [iesb] , [ iparm] , [ids] ) 

rtname = Taryet task name of the offspring task to ae 
connected 

ibuf = Address of 13-word send buffer 

iefn = Event flay to be set when the offspring task exits 
or emits status 

iast = Address of an AST routine to be called when the 
offspririg task exits or emits status 

iesb = Address of an 8-word status block to be written when 
the offspring task exits or emits status 

word -- Offspring task exit status 

word 1-7 — Reserved 

iparm = Address of a word to receive the status block 
address when an AST occurs 

= Integer to receive the Directive Status Word 



tname,buf,efn,east,esb 

Target task name of the offspring task to bo 
connected 

= Address ot 13-word send buffer 

The event flag to be cleared on issuance and set 
when the offspring task exits or emits status 

east = Address of an AST routine to be called when the 
offspring task exits or emits status 

esb = Address of an 8-word status block to be written when 
the offspring task exits or emits status 

word — Offspring task exit status 
v;orQ 1-7 — Reserved 





ids 


Macro 


Call: 




SDRC$ 




tname 




buf 




efn 
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:■■: ALPHA/] 


.BYTE 


/■■■V:.14.t..,? 


.RAD50 


■ALPHA- 


.WOUD 


■:-.::-BUPtR,-- 


.WORD 


■■-ri.' :.^ 


• WOUD 


: SbRG^R 


.WORD 


.■■-STBLK-' 



DIRECTIVE DESCRIPTIONS 

Macro Sxpansion: 

ALPHA,BUFFR,2,SDRCTR,STELK '^^' 

;SDRC$ MACRO :DIC, DPB SIZE=7 WORDS 
; TARGET TASK NAME 
;SEND BUFFER ADDRESS 
■ '; EVENT FLAG NUMBER = 2 
; ADDRESS OF AST ROUTINE 
;APDRESS OP STATUS BLOCK 

Local Synbol Def initiohs: 

S.DRTN — Ta?k .name (4): 

S.DR3F — Bu^fjEer address ( 2):- ^;--\: 

S.DRSF — Event' flag (2) 

S.DRSA -- AST routine address/C!) 

S.DRES — Status block address (2)-; ; 
DSW Return Codes: -v;^ " "X ■ 

IS . sue — SucGessf ul completion 

lE.UFN — Insufficient dynamic ^lemory to allocate a send 
packet. Offspring Control Block, Task Control Block, 
or Partition Control Block 



,^^^^\^ 



IE. INS — The specified task is an ACP or has the no-send 
attrl&u'te -"■■■..■ 

lE.lEF -- An invalid event flag number was specified 

lE.ADP — Part of; the DPB or exit status block is not in the 
issuincj task' s add resss space 

lE.SDP — Die or DPB size 'is- invalid 



^^^Wli 
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SETF$ 

6.3.54 Set Event Flag 

The Set Event Flag directive instructs the system to set an indicated 
event flag, reporting the flag's polarity before setting. 

FORTRAN Call: 

CALL SETEF (efn[,ids]) 

efn = Event flag number 

ids = Directive status 

Macro Call: 

SETF$ efn 

efn = Event flag number 

Macro Expansion: 

SETF$ 52. 

.BYTE 33., 2 ;SETF$ MACRO DIC, DPB SIZE=2 WORDS 

.WORD 52. ; EVENT FLAG NUMBER 52. 

Local Symbol Definitions: 

S.ETEF — Event flag number (2) 
DSW Return Codes: 

IS.CLR — Flag was clear 

IS. SET — Flag was already set 

lE.IEF — Invalid event flag number {>64 or <1) 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 

lE.SDP — DIC or DPB size is invalid 

Note: 

Set Event Flag does not declare a significant event; it merely 
sets the specified flag. 
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6.3.55 Specify Floating Point Processor Exception AST 

The Specify Floating Point Processor Exception AST directive instructs 
the system to record one of the two following cases: 

• Floating Point Processor exception ASTs for the issuing task 
are desired, and the Executive is to transfer control to a 
specified address when such an AST occurs for the task 

• Floating Point Processor exception ASTs for the issuing task 
are no longer desired. 

When as AST service routine entry point address is specified, future 
Floating Point Processor exception ASTs will occur for the issuing 
task, and control will be transferred to the indicated location at the 
time of the AST's occurrence. When an AST service entry point address 
is not specified, future Floating Point Processor exception ASTs will 
not occur until the task issues a directive that specifies an AST 
entry point. See Notes below. 

FORTRAN Call: 

Not supported 
Macro Call: 

SFPA$ [ast] 

ast = AST service routine entry point address 

Macro Expansion: 

SFPA$ FLTAST 

.BYTE 111., 2 ;SFPA$ MACRO DIC, DPB SIZE=2 WORDS 

.WORD FLTAST /ADDRESS OF FLOATING POINT AST 

Local Symbol Definitions: 

S.FPAE — AST entry address (2) 
DSW Return Codes: 

IS. sue — Successful completion 

lE.UPN — Insufficient dynamic memory 

IE. ITS — AST entry point address is already unspecified or 
task was built without floating-point support (FP 
switch not specified in Task Builder .TSK file 
specification) 

IE. AST — Directive was issued from an AST service routine, or 
ASTs are disabled 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 

lE.SDP — Die or DPB size is invalid 



WP^^PWK 



.^^ffli 
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Notes: 



1. Specify Floating Point Processor Exception AST requires 
dynamic memory. 

2. The Executive queues Floating Point Processor exception ASTs 
when a Floating Point Processor exception trap occurs for the 
task. No future ASTs of this kind will be queued for the 
task until the first one queued has actually been effected. 

3. The Floating Point Processor exception AST service routine is 
entered with the task stack in the following state: 

SP+12 - Event flag mask word 
SP+10 - PS of task prior to AST 
SP+06 - PC of task prior to AST 
SP+04 - DSW of task prior to AST 
SP+02' - Floating exception code 
SP+00 - Floating exception address 

The task must remove the floating exception code and address 
from the task's stack before an AST Service Exit (see Section 
6.3.4) directive is executed. 

4. This directive cannot be issued from an AST service routine 
or when ASTs are disabled. 

5. This directive applies only to the Floating Point Processor. 
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^P^B|k 



6.3.56 Specify Parity Error AST 

Trie Specify Parity Error AST directive enables a task to specify an 
AST service routine to be entered if a hardware parity error occurs. 
If an AST address is not specified, any previously specified parity 
error AST is canceled. Upon entering the AST service routine, the 
stack contains the following information: 



SP+6 2 
SP+60 
3P+56 
SP+54 
SP+52 
SP + 50 
3P + 46 
SP+44 
SP + 42 
SP + 40 
SP+36 
SPx34 
SP + 32 
SP+30 
SP + 26 
SP+24 
SP+22 
SP+20 
SP + 16 
SP + 14 
SP+12 
SP+10 
SP+06 
SP+04 
SP+02 
SP + 00 



Event flag mask word 
PS of task prior to AST 
PC of task prior to AST 
Task's directive status word 



Contents of memory parity CSRs 
(hardware-dependent information) 



-- Contents of cache control register 

— Contents of memory systen error register 

— Contents of high error acdress register 

— Contents of low error address register 

— Processor identification (single processor system=0) 

— Number oC bytes to add tc SP to clean the stack (52) 



FOfVl'RAN Call: 

Not supported 
Macro Call: 

SPEA$ [ast] 

ast = AST service routine entry point address 
Macro Expansion: 



SPEA$ PTYERR 
.BYTE 165. ,2 
.WORD PTYERR 



;SPEA$ MACRO DIC, DPB SIZE=2 WORDS 
; PARITY iRROR AST ROUTINE ADDRESS 



Local Symbol Definitions: 

S.PEAE — Parity error AST routine address (2) 

DSW Return Codes: 

IS. sue -- Successful completion 
lE.UPN -- Insufficient dynamic f.torage 
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IE. AST — Directive waa i-=&ued fron an AST service routine, or 
ASTa are disabled 

lii.ADP -- Part o£ the DPB is out of the issuing task's address 
space 



IE. SOP — DIG or DPB size is invalid 
IE. ITS — ASTs al ruady not desired 
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SPND$S 

6.3.57 Suspend ($s form recommended) 

The Suspend directive instructs the system to suspend the execution of 
the issuing task. A task can suspend only itself, not another task. 
The task can be restarted either by a Resume directive, or bv an MCR 
Resume command. ' 

FORTRAN call: 

CALL SUSPND [ (ids) ] 

ids = Directive status 

Macro Call: 

SPND$S [err] 

err = Error routine address 

Macro Expansion: 



SPND$S ERR 

MOV (PC)+,-(SP) 

.BYTE 45. ,1 

EMT 377 

BCC .+6 

JSR PC, ERR 



;PUSH DPB ONTO THE STACK 

;SPND$S MACRO DIG, DPB SI2E=1 WORD 

;TRAP TO THE EXECUTIVE 

; BRANCH IF DIRECTIVE SUCCESSFUL 

/OTHERWISE, CALL ROUTINE "ERR" 



Local Symbol Definitions: 

None 
DSW Return Codes: 

IS.SPD — Successful completion (task was suspended) 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 



lE.SDP — Die or DPB size is invalid 



Notes; 



A suspended task retains control of the system resources 
allocated to it. The Executive makes no attempt to free 
these resources, until a task exits. 

A suspended task is eligible for checkpointing unless it is 
fixed or declared to be noncheckpointable. 

Because this directive requires only a 1-word DPB, the $S 
form of the macro is recommended. It requires less space and 
executes with the same speed as the DIR$ macro. 
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6.3.58 Specify Power Recovery AST 

The Specify Power Recovery AST directive instructs the system to 
record one of the two following cases: 

1. Power recovery ASTs for the issuing task are desired, and 
control is to be transferred when a powerfail recovery AST 
occurs. 

2. Power recovery ASTs for the issuing task are no longer 
desired . 

When an AST service routine entry point address is specified, future 
power recovery ASTs will occur for the issuing task, and control will 
be transferred to the indicated location at the time of the AST s 
occurrence. When an AST service entry point address is not specified, 
future power recovery ASTs will not occur until an AST entry point is 
again specified. See Notes below. 

FORTRAN Call 

To establish an AST 

EXTERNAL sub 
CALL PWRUP (sub) 

sub == Name of a subroutine to be executed upon power 
recovery. The PWRUP subroutine will effect a 

CALL sub (no arguments) . 

The subroutine is called as a result of a power 
recovery AST and therefore may be controlled at 
critical points by using DSASTR and ENASTR subroutine 
calls. 

To remove an AST 

CALL PWRUP 
Macro Call: 

SPRA$ [ast] 

ast •= AST service routine entry point address 

Macro Expansion: 

SPRA$ PWRAST 

BYTE 167., 2 ;SPRA$ MACRO DIG, DPB SIZE=2 WORDS 

.WORD PWRAST /ADDRESS OF POWER RECOVERY AST 

Local Symbol Definitions: 

S.PRAE — AST entry address (2) 
DSW Return Codes: 

IS. sue — Successful completion 
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lE.UPN — Insufficient dynamic memory 

IE. ITS — AST entry point address is already unspecified 

IE. AST — Directive was issued from an AST service routine, or. 
ASTs are disabled 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 

IE. SOP — DIG or DPB size is invalid 
Notes: 

1. Specify Power Recovery AST requires dynamic memory. 

2. The Executive queues power recovery ASTs when the power-up 
interrupt occurs following a power failure. No future 
powerfail ASTs will be queued for the task until the first 
one queued has been effected,, 

3. The task enters the powerfail AST service routine with the 
task stack in the following state: 

SP+06 - Event flag mask word 

SP+04 - PS of task prior to AST 

SP+02 - PC of task prior to AST 

SP+00 - DSW of task prior to AST 

No trap-dependent parameters accompany a power recovery AST- 
therefore, the AST Service Exit directive (see Section 6.3.4) 
can be executed with the stack in the same state as when the 
AST was entered . 

4. This directive cannot be issued from an AST service routine 
or when ASTs are disabled. 



-^^^^^li 
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6.3.59 Spawn 

The Spawn directive requests a specified task for execution, 
optionally queuing a command linel, and establishing the tasic s ii: 

as a:§iP;^;|ouslyffpi£:ated vii1|Wi|B;^«|"i'"^3l 'J^ttSifS P'^^^^^^^ terminal. 

When this directive is issued, an Offspring Control Block (OCB) is 
queued to the offspring TCB and a rundown count is incremented in the 
parent task's TCB. The rundown count is used to inform the Executive 
that the task is a parent task and has one or more offspring tasks and 
wi«*»l;i;Mf"tt«a*Mi;:CWi.?f- cleanup is necessary if a parent task exits with 
^^lilHflpling tasks. The rundown count is decremented when the 
spawned task exits,. The OCB contains the TCB address as well as 
sufficient information to effect all of the specified exit events when 
the offspring task exits. 

If a command line is specified, it is buffered in the Executive pool 
and queued for the offspring task for subsequent retrieval by the 
offspring task via the Get MCR Command Line directive. Maximum 
command line length is 79 characters. 

If an AST address is specified, an exit AST routine is effected when 
the spawned task exits with the address of the task's exit status 
block on the stack. The AST routine must remove this word from tne 
stack before issuing the AST Service Exit directive. 

Special action is taken if the task being spawned is a Command Line 
Interpreter (CLI) , such as MCR orDCL. , In this case, a command line 
must be specified, and both the OCB and the command line ^^^^ ., .^^^^^f, 
for the interpreter task. MCR aDd DCL either handle commands directly 
or dispatch them to another task. In the case of direct execution ot 
the command, the OCB may be used to immediately effect the Pi^oP^^^^^i^ . 
conditions and return exit status via an Executive routine. If. ^CR #r ■ 
Klift' dispatch another task, they simply move the OCB from their own OCB 
"queue directly to the OCB queue of the dispatched task. They also 
queue the command line for the dispatched task as usual. At this 
point, the situation is exactly the same as if the SPWN$ directive had 
specified the dispatched task directly. No exit conditions occur 
until the dispatched task exits. 

FORTRAN call: 

CALL SPAWN (rtname,[iugc] ,[iumc] ,[iefn] ,[iast] ,[iesb] ,[iparm] , 
[icmlin] , [icmlen] , [iunit] , [dnam] , [ids] ) 

rtname = Name of the offspring task to be spawned 

iugc = Group code number for the UIC of the offspring task 

iumc = Member code number for the UIC of the offspring task 

iefn = Event flag to be set when the offspring task exits 
or emits status 

last = Address of an AST routine to be called when the 
offspring task exits .oi'v:#Ril!.tX.'';S"t,fft'ifS'' 



1 Command line processing is not available for RSX-llS tasks, 



6-131 



DIRECTIVE DESCRIPTIONS 



iesb = Address of an 8-word status block to be written when 
the offspring task exits or emits status 

word — Offspring task exit status 

word 1-7 — Reserved 

iparm = Address of a word to receive the status block 
address when the AST occurs 

icmlin = Address of a command line to be queued for the 
offspring task 

icmlen = Length of the command line (79. characters maximum) 

iunit = Unit number of terminal to be used as the TI : for 
the offspring task. If the optional dnan parameter 
is not specified, this parameter must be the unit 
number of a virtual terminal created by the issuing 
task; if a value of is specified, the TI : of the 
issuing task is propagated. A task must be 
privileged in order to specify a TI : other than the 
parent task' s TI : . 



dnam 

ids 
Macro Call: 
SPWN$ 

tnarae 
ugc 
umc 
efn 

east 

esb 



= Device name mnemonic. If not specified, the virtual 

::te:rmlnal.:.is^.used as Tl:. 

Integer to receive the directive status word 



tname, , , [ugc] , [umc] , [efn] ,, [east] , [esb] , [cmdlin] , [cmdlen] , 
[unum] , [dnam] 

Name of the offspring task to be spawned 

= Group code number for the UIC of the offspring task 

= Member code number for the UIC of the offspring task 

= The event flag to be cleared on issuance and set 
when the offspring task exits o;r:;;^jhtt$r?S-t:af JiSj 

= Address of an AST routine to be called when the 
offspring task exits or emits status 

= Address of an 8-word status block to be written when 
the offspring task exits or emits status i 

word — Offspring task exit status 

word 1-7 — Reserved 

cmdlin = Address of a command line to be queued for the 
offspring task 

cmdlen = Length of the command line (maximum length is 79.) 

unum = Unit number of terminal to be used as the TI : for 
the offspring task. If the optional dnam parameter 
i:^:ndt -Specif ied , this pai^ameter must be the unit 
number of a virtual terminal created by the issuing 
task; if a value of is specified, the TI: of the 



^^'^fm 



^^^W%^ 



6-132 



DIRECTIVE DESCRIPTIONS 



dnam 



Macro Expansion: 



SPWN$ 


ALPHA, , 


.BYTE 


11. ,13. 


.RAD50 


ALPHA 


.BLKW 


3 


.BYTE 


7,3 


.WORD 


1 


.WORD 


ASTRUT 


.WORD 


STBLK 


.WORD 


CMDLIN 


• WORD 


72. 


.WORD 


2 



issuing task is propagated. A task must be 
privileged in order to specify a TI : other than the 
parent task's TI : . 

Device name mnemonic. If not specified, the virtual 
terminal is used as TI:. 



,3,7,1,ASTRUT,STBLK,CMDLIN,72. ,2 

SPWN$ MACRO Die, DPS SIZE=13 WORDS 

NAME OF TASK TO BE SPAWNED 

RESERVED 

UMC = 7 UGC = 3 

EVENT FLAG NUMBER = 1 

AST ROUTINE ADDRESS 

EXIT STATUS BLOCK ADDRESS 

ADDRESS OF COMMAND LINE 

COMMAND LINE LENGTH = 72. CHARACTERS 

VIRTUAL TERMINAL UNIT NUMBER =2 



NOTE 

•Jf, a y-ir,tual -fcerm.i'nal is- n'Q:t-->jHeci-£ie_df 
one additional parameter (device name) 
can be added for a hardware terminal 
name. For example, TT2 ila«.t^f|(i-;<^f.: V_f i?) 
would have the same macro ' expansion 
shown above, plus the following: 

.ASCII /TT/ ; ASCI I DEVICE NAME 

The DPB size will then be 14 words. 



Local Symbol Definitions: 

S.PWTN — Task name (4) 

S.PWXX — Reserved (6) 

S.PWUM — User member code (1) 

S.PWUG — User group code (1) 

S.PWEF — Event flag number (2) 

S.PWEA — Exit AST routine address (2) 

S.PWES — Exit status block address (2) 

S.PWCA — Command line address (2) 

S.PWCL — Command line length (2) 

S.PWVT — Terminal unit number (2) 

S.PWDN — Device name (2) 

DSW Return Codes: 

IS. sue — Successful completion 
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lE.UPN — Insufficient dynamic memory to allocate an offspring 
control block, command line buffer, task control 
block, or partition control block 

IE. INS — The specified task was not installed, or it was a 
command line interpreter but no command line was 
specified 

IE. ACT — The specified task was already active and it was not 
a command line interpreter. 

lE.IDU — The specified virtual terminal unit does not exist, 
or it was not created by the issuing task 

lE.IEF — An invalid event flag number was specified 

lE.ADP — Part of the DPB, exit status block, or command line 
is out of the issuing task's address space 

lE.SDP — Die or DPB size is invalid 



JW^t|^^ 
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6.3.60 Specify Receive Data AST 

The Specify Receive Data AST directive instructs the system to record 
one of the following two cases: 

• Receive data ASTs for the issuing task are desired, and the 
Executive transfers control to a specified address when data 
have been placed in the task's receive queue 

• Receive data ASTs for the issuing task are no longer desired. 

When the directive specifies an AST service routine entry point, 
receive data ASTs for the task will subsequently occur whenever data 
have been placed in the task's receive queue; the Executive will 
transfer control to the specified address. 

When the directive omits an entry point address, the Executive 
disables receive data ASTs for the issuing task. Receive data ASTs 
will not occur until the task issues another Specify Receive Data AST 
directive that specifies an entry point address. See Notes below. 

FORTRAN Call: 

Neither the FORTRAN language nor the ISA standard permits direct 
linking to system trapping mechanisms; therefore, this directive 
is not available to FORTRAN tasks. 

Macro Call: 

SRDA$ [ast] 

ast = AST service routine entry point address 

Macro Expansion: 

SRDA$ RECAST 

.BYTE 107., 2 ;SRDA$ MACRO DIC, DPB SIZE=2 WORDS 

.WORD RECAST ; ADDRESS OF RECEIVE AST 

Local Symbol Definitions: 

S.RDAE — AST entry address (2) 
DSW Return Codes: 

IS. sue — Successful completion 

lE.UPN — Insufficient dynamic memory 

IE. ITS — AST entry point address is already unspecified 

IE. AST — Directive was issued from an AST service routine, or 
ASTs are disabled 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 

lE.SDP — DIC or DPB size is invalid 
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Notes: 

1. Specify Receive Data AST requires dynamic memory. jdlt 

2. The Executive queues receive data ASTs when a message is sent 
to the task. No future receive data ASTs will be queued for 
the task until the first one queued has been effected. 

3. The task enters the recieve data AST service routine with the 
task stack in the following state: 

SP+06 - Event flag mask word 

SP+04 - PS of task prior to AST 

SP+02 - PC of task prior to AST 

SP+00 - DSW of task prior to AST , 

No trap-dependent parameters accompany a receive data AST; 
therefore, the AST Service Exit directive (see Section 6.3.4) 
must be executed with the stack in the same state as when the 
AST was effected. 

4. This directive cannot be issued from an AST service routine jga^ 
or when ASTs are disabled. ■"" ' 1) 



^™?l^^ 
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6.3.61 Specify Requested Exit AST 

The Specify Requested Exit AST directive allows the task issuing the 
directive to specify the AST service routine to be entered if an 
attempt is made to abort the task by directive or MCR. This allows a 
task to enter a routine instead of abruptly aborting. Privileged 
tasks enter the specified AST routine each time an abort is issued. 
However, future abort ASTs will not be queued until the first abort 
AST has been effected. However, nonpr ivileged tasks enter the 
specified AST only once; subsequent attempts to abort the task will 
result in the task being aborted. If an AST address is not specified, 
any previously specified exit AST is canceled. 

FORTRAN Call: 

Not supported 
Macro Call: 

SREA$ [a St] 

ast = AST service routine entry point address 

Macro Expansion: 

RECAST 

;SREA$ MACRO DIG, DPB S1ZE=2 WORDS 
;EXIT AST ROUTINE ADDRESS 

Local Symbol Definitions: 

S.REAE — Exit AST routine address (2) 
DSW Return Codes: 

IS. sue — Successful completion 

lE.UPN -- Insufficient dynamic storage 

IE. AST — Directive was issued from an AST service routine, or 
ASTs are disabled 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 

lE.SDP — Die or DPB size is invalid 

IE. ITS -- AST's already not desired or nonpr ivileged task 
attempted to respecify the AST after it had occurred 
once. 



SREAS 


RECAST 


.BYTE 


87., 2 


.WORD 


REQAST 
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6.3.6 2 Send By Reference 

The Send By Reference directive inserts a packet containing a 
reference to a region into the receive-by-reference queue of a 
specified (receiver) task. The Executive automatically attaches the 
receiver task for each Send By Reference directive issued by the task -> 

to the specified region (the region identified in W.NRID of the Window 
Definition Block) . The attachment occurs even if the receiver task is 
already attached to the region, unless bit WS.NAT in W.NSTS of ,th,e 
:;W;EncJoWv::;De:Ei^^^ set. The successful execution of this 

directive causes a significant event to occur. ^ 

The send packet contains: 

• A pointer to the created attachment descriptor, which becomes 
the region ID to be used by the receiver task 

• The offset and length words specified in W.NOFF and W.NLEN of ^^ 
the Window Definition Block (which the Executive passes ^^i 
without checking) 

• The receiver task's permitted access to the region, contained 
in the window status word W.NSTS 

• The sender task name 

• Optionally, the address of an 8-word buffer that contains 
additional information (If the packet does not include a 

buffer address, the Executive sends eight words of 0.) 4*111^. 

The receiver task automatically has access to the entire region as 
specified in W.NSTS. The sender task must be attached to the region 
with at least the same types of access. By setting all the bits in 
W.NSTS to 0, the permitted access can be defaulted to that of the 
sender task. 

If the directive specifies an event flcig, the Executive sets the flag 

in the sender task when the receiver task acknowledges the reference 

by issuing the Receive By Reference directive (see Section 6.3.48). 

When the sender task exits, the system searches for any unreceived ^^^ 

references that specify event flags, and prevents any invalid attempts ""T^ 

to set the flags. The references themselves remain in the receiver 

task's receive-by-reference queues. 

FORTRAN Call: 

CALL SREF ( tsk , [ef n] , iwdb, [ isrb] [ „ ids] 

tsk = A single precision, floating-point variable containing • 

the name of the receiving task in Radix-50 format 

efn = Event flag number 

iwdb = An 8-word integer array containing a Window Definition 

Block (see Section 3.5.2.2) " 

isrb = An 8-word integer array containing additional 
information (If specified, the address of isrb is 
placed in iwdb(8) . If isrb is omitted, the contents 
of iwdb(8) remain unchanged.) 0%^ 
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ids = Directive status 
Macro Call: 

SREF$ task,wdb[ ,efn] 

task = Name of the receiver task 

wdb = Window Definition Block address 

efn = Event flag number 
Macro Expansion: 

SREF$ ALPHA, WDBADR, 48. 



.BYTE 69., 5 

.RAD50 /ALPHA/ 

•WORD 48. 

.WORD WDBADR 



SREF$ MACRO DIC, DPB SIZE=5 WORDS 
RECEIVER TASK NAME 
EVENT FLAG NUMBER 
WDB ADDRESS 



Window Definition Block Parameters: 

Input parameters 

Array 

Element Offset 

iwdb(4) W.NRID — ID of the region to be sent by reference 

iwdb(5) W.NOFF — Offset word, passed without checking 

iwdb(6) W.NLEN — Length word, passed without checking 

iwdb(7) W.NSTS — Bit settings! in window status word (the 

receiver task's permitted access): 

WS.RED — 1 if read access is permitted 

WS.WRT — 1 if write access is permitted 

WS.EXT — 1 if extend access is permitted 

WS.DEL — 1 if delete access is permitted 

iwdb(8) W.NSRB — Optional address of an 8-word buffer 

containing additional information 

Output para meters 

None 
Local Symbol Definitions: 

S.RETN — Receiver task name (4) 

S.REBA — Window Definition Block base address (2) 

S.REEF — Event flag number (2) 



■'- FORTRAN programmers should refer to Section 3.5.2 to determine the 
bit values represented by the symbolic names described. 
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DSW Return Codes: 

IS. sue — Successful completion ^^ 

lE.UPN — A send packet or an attachment descriptor could not 
be allocated 

IE. INS — The sender task attempted to send a reference to an 
Ancillary Control Processor (ACP) task, or task not 
installed 

lE.PRI — Specified access not allowed to sender task itself 

lE.NVR — Invalid region ID 

lE.IEF — Invalid event flag number 

lE.ADP — The address check of the DPB, the WDB, or the send 
buffer failed 



lE.HWR — Region had load failure or parity error 
lE.SDP — Die or DPB size is invalid 



Notes! 



;^^^^^|fc 



1. For the user's convenience, the ordering of the SREF$ macro 
arguments does not directly correspond to the format of the 
DPB. The arguments have been arranged so that the optional 
argument (efn) is at the end of the macro call. This 
arrangement is also compatible with the SDAT$ macro. 

2. Because region attachment requires system dynamic memory, the 0Ktk^ 
receiver task should detach from any region that it was ^ 
already attached to, in order to prevent depletion of the 

memory pool. That is, the task needs to be attached to a 
given region only once. 



.-7^^^^!?7!& 



-ff^^'nHl^ffife 
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SRRA$ 



6.3.63 Specify Receive-By-Reference AST 

The Specify Receive-By-Reference AST directive instructs the system to 
record one of the following two cases: 

• Receive-by-reference ASTs for the issuing task are desired, 
and the {executive transfers control to a specified address 
when such an AST occurs. 

• Receive-by~reference ASTs for the issuing task are no longer 
desired . 

When the directive specifies an AST service routine entry point, 
receive-by-reference ASTs for the task will occur: the Executive will 
transfer control to the specified address. 

When the directive omits an entry point address, the Executive stops 
the occurrence of receive-by-reference ASTs for the issuing task. 
Receive-by-reference ASTs will not occur until the task issues another 
Specify Receive-By-Reference AST directive that specifies an entry 
point address. See Notes below. 

FORTRAN Call: 

Neither the FORTRAN language nor the ISA standard permits direct 
linking to system-trapping mechanisms; therefore, this directive 
is not available to FORTRAN tasks. 

Macro Call: 

SRRA$ [ast] 

ast = AST service routine entry point address (0) 

Macro Expansion: 

:ast 

;srra$ macro dic , dpb size=2 words 
/address of receive ast 

Local Symbol Definitions: 

S.RRAE — AST entry address (2) 
DSW Return Codes: 

IS. sue — Successful completion 

lE.UPN — Insufficient dynamic memory 

IE. ITS — AST entry point address is already unspecified 

IE. AST — Directive was issued from an AST service routine, or 
ASTs are disabled 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 

lE.SDP — DIC or DPB size is invalid 
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RECAST 


.BYTE 


21. ,2 


.WORD 


RECAST 
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Notes: 

1. Specify Receive-By-Reference AST requires dynamic memory. ^^^ 

2. The Executive queues receive-by-reference ASTs when a message 
is sent to the task. Future receive-by-reference ASTs will 
not be queued for the task until the first one queued has 
been effected, 

3. The task enters the receive-by-reference AST service routine 
with the task stack in the following state: 

SP+06 - Event flag mask word 

SP+04 - PS of task prior to AST 

SP+02 - PC of task prior to AST * 

SP+00 - DSW of task prior to AST 

No trap-dependent parameters accompany a receive-by-reference 
AST; therefore, the AST Service Exit directive (see Section 
6.3.4) must be executed with the stack in the same state as 
when the AST was effected. 

4. This directive cannot be issued from an AST service routine 
or when ASTs are disabled. 



4^Mfflk 
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6.3.64 Set Affinity 

The Set Affinity directive can be issued by a task to select which CPU 
and UNIBUS run(s; to use duriny task execution. This directive can 
only be issued for RSX-ilM-PLUS tasks that are executed on PDP-11 
multiprocessor systems. 

A 1-word CPU/UNIE)US affinity mask defines directive parameters. 
Parameters enable specification of one of four (maximum) CPUs and one 
or more of twelve (maximum) UNIBUS runs. All parameters are ORed at 
assembly time to form the affinity mask word. Only one parameter (cp 
or ub) is required. Directive parameters are assembled to produce the 
mask word bit values shown as follows; 

Directive Assembled 

Par ameter Mask Word Function Bit Value 

CPA Select CPU "A" 1 

CPB Select CPU "B" 2 

CPC Select CPU "C" 4 

CPD Select CPU "D" 10 

UBi; Select UNIBUS run "E" 20 

UBF Select UNIBUS run "F" 40 

UBH Select UNIBUS run "H" 100 

UBJ Select UNIBUS run "J" 200 

UBK Select U>CIBUS run "K" 400 

UBL Select UNIBUS run "L" 1000 

UBM Select UNIBUS run "M" 2000 

UBN Select UNIBUS run "N" 4000 

UEP Select UNIBUS run "P" 10000 

UBR Select UNIBUS run "U" 20000 

UBS Select UNIBUS run "G" 40000 

UBT Select UNIBUS run "T" 100000 

FORTRAN call: 

CALL STAF (iaff , [ids] ) 

iaff = Affinity mask word 

ids = Integer to receive Directive Status Word 

Macro Call: 

STAF$ [cp! ubl ub . . . ] 

cp = CPU selected (A through D, as previously listed) 

ub = UNIBUS run selected ( tl through T, as previously listed) 

Macro Expansion: 

STAF5 CPB!'JDF!UBJ 

.BYTE 161., 2 ;STAF$ MACRO DIC, DPB SIZE=2 WORDS 

.WORD 242 ; AFFINITY MASK WORD ('OR' OF PARAMETERS) 

Local Symbol Definitions: 

S.AFAF -- Affinity mask word (2) 
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DSW Return Codes: 

IS. sue — Successful completion 

IE.3DP — Die or DPB size is invalid 

IE. ITS — Task installed with cffinity 

lE.ADP — Part of the DPB is ou.t of the issuing task's address 
space 



Notes: 



1. A task that is installed witl- task affinity must not issue 
this directive. Any atteirpt to do so results in an IE. ITS 
error returned. 

2. If this directive is issued with parameters that prevent the 
task from running an IE. ITS error is returned. 
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6.3.65 Stop For Logical OR Of Event Flags 

The Stop For Logical OR Of Event Flags directive instructs the system 
to stop the issuing task until the Executive sets one or more of the 
indicated local event flags from one of the following groups: 

GR — Flags 1-16 

GR 1 — Flags 17-32 

The task does not stop itself if any of the indicated flags are 
already set when the task issues the directive. This directive cannot 
be issued at AST state. 

A task that is stopped for one or more event flags can only become 
unstopped by setting the specified event flag; it cannot become 
unstopped via the Unstop directive. 

FORTRAN Call: 

CALL STLOR ( ief 1 , ief 2 , ief 3 , ... ief(n)) 

iefl „.. ief(n) = List of event flag numbers 

Macro Call: 

STLO$ grp, msk 

grp = Desired group of event flags 

msk == A 16-bit mask word 

Macro Expansion: 



STLO$ 1,47 

.BYTE 137., 3 

.WORD 1 

.WORD 47 



STLO$ MACRO DIC, DPB SIZE=3 WORDS 

GROUP 1 FLAGS (FLAGS 17-32) 

MASK WORD = 47 (FLAGS 17, 18, 19, 22) 



Local Symbol Definitions: 

S.TLGR — Group flags (2) 

S.TLMS — Mask word (2) 
DSW Return Codes: 

IS. sue — Successful completion 

IE, AST — The issuing task is at AST state 

IE. IEF — An event flag group other than or 1 was specified 
or the event flag mask word is zero 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 

lE.SDP — DIC or DPB size is invalid 



6-145 



DIRECTIVE DESCRIPTIONS 



Notes: 



1. There is a one-to-one correspondence between bits in the mask 
word and the event flags in the specified group. That is, if 
group 1 were specified (as in the above macro expansion 
example), bit in the mask word would correspond to event 
flag 17, bit 1 to event flag 18, and so forth. 

2. The Executive does not arbitrarily clear event flags when 
Stop For Logical OR Of Event Flags conditions are met. Some 
directives (Queue I/O Request, for example) implicilty clear 
a flag; otherwise, they must be explicitly cleared by a 
Clear Event Flag directive. 

3. The argument list specified in the FORTRAN call must contain 
only event flag numbers that lie within one event flag group. 
If event flag numbers are specified that lie in more than one 
group, or if an invalid event flag number is specified, a 
fatal FORTRAN error is generated. . 

4. Tasks stopped for event flag conditions cannot be unstopped 
by issuing the Unstop directive; tasks stopped in this 
manner can only be unstopped by meeting event flag 
conditions. 

5. The grp operand must always be of the form n regardless of 
the macro form used. In all other macro calls, numeric or 
address values for $S form macros have the form: 

#n 

For STLO$S this form of the grp argument would be: 

n 



■^^^ 
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STOP$S 



6.3.66 Stop ($S form recommended) 

The Stop directive stops the issuing task. This directive cannot be 

issued at AST state. A task stopped in this manner can only be 

unstopped by another task that issues an Unstop directive directed to 
this task. 

FORTRAN Call: 

CALL STOP ( [ids] ) 

ids = Integer to receive the directive status word 

Macro Call: 
STOP$S 
Macro Expansion: 

stopSs 

.byte' 131., 1 ;ST0P$ MACRO DIG, DPB SIZE=1 WORD 

Local Symbol Definitions: 

None 
DSW Return Codes: 

IS. SET — Successful completion 

IE. AST — The issuing task is at AST state 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 

lE.SDP — Die or DPB size is invalid 
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STSE$ 

6.3.67 Stop For Single Event Flag 

The Stop For Single Event Flag directive instructs the system to stop 
the issuing task until the specified local event flag is set. If the 
flag is set at issuance, the task is not stopped. This directive can 
not be issued at the AST state. 

A task that is stopped for one or more event flags can only become 
unstopped by setting the specified event flag; it cannot become 
unstopped via the Unstop directive. 

FORTRAN Call: 

CALL STOPFR {iefn,[ids]) 

iefn = Event flag number 

ids = Integer to receive directive status word 

Macro Call: 

STSE$ efn 

efn = Event flag number 

Macro Expansion: 

STSE$ 7 

•BYTE 135., 2 ;STSE$ MACRO DIC, DPB SIZE=2 WORDS 

.WORD 7 ; LOCAL EVENT FLAG NUMBER = 7 

Local Symbol Definitions: 

S.TSEF — Local event flag number (2) 

DSW Return Codes: 

IS. sue — Successful completion 

IE. AST — The issuing task is at AST state 

lE.IEF — An event flag number other than a local event flag 
was specified (not in the range 1-32) 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 

lE.SDP — DIC or DPB size is invalid 






.^iPI^^ 
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6.3.68 Specify SST Vector Table For Debugging Aid 

The Specify SST Vector Table For Debugging Aid directive instructs the 
system to record the address of a table of SST service routine entry 
points for use by an intra-task debugging aid (ODT, for example) . 

To deassign the vector table, omit the parameters adr and len from the 
macro call. 

Whenever an SST service routine entry is specified in both the table 
used by the task and the table used by a debugging aid, the trap 
occurs for the debugging aid, not for the task. 

FORTRAN Call: 

Neither the FORTRAN language nor the ISA standard permits direct 
linking to system trapping mechanisms; therefore, this directive 
is not available to FORTRAN tasks. 

Macro Call: 

SVDB$ [adr] [,len] 

adr = Address of SST vector table 

len = Length of (that is, number of entries in) the table in 
words 

The vector table has the following format: 

word — Odd address of nonexistent memory error 

word 1 — Memory protect violation 

word 2 — T-bit trap or execution of a BPT instruction 

word 3 — B:xecution of an lOT instruction 

word 4 — Execution of a reserved instruction 

word 5 — Execution of a non-RSX EMT instruction 

word 6 — Execution of a TRAP instruction 

word 7 — PDP-11/40 floating point exception 

A entry in the table indicates that the task does not want to 
process the corresponding SST. 

Macro Expansion: 



SVDB$ SSTTBL,4 

.BYTE 105., 3 

.WORD SSTTBL 

.WORD 4 



SVDB$ MACRO DIG, DPB SIZE=3 WORDS 
ADDRESS OF SST TABLE 
SST TABLE LENGTH=4 WORDS 
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Local Symbol Definitions: 

S.VDTA — Table address (2) ^^ 

S.VDTL — Table length (2) 
DSW Return Codes: 

IS. sue — Successful completion 

lE.ADP — Part of the DPB or table is out of the issuing task's 
address space 

lE.SDP — Die or DPB size is invalid 



-^^^Iv 
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6.3.69 Specify SST Vector Table For Task 

The Specify SST Vector Table For Task directive instructs the system 
to record the address of a table of SST service routine entry points 
for use by the issuing task. 

To deassign the vector table, omit the parameters adr and len from the 
macro call. 

Whenever an SST service routine entry is specified in both the table 
used by the task and the table used by a debugging aid, the trap 
occurs for the debugging aid, not for the task. 

FORTRAN Call: 

Neither the FORTRAN language nor the ISA standard permits direct 
linking to system trapping mechanism; therefore, this directive 
is not available to FORTRAN tasks. 

Macro Call: 

SVTK$ [adr] [,len] 

adr = Address of SST vector table 

len = Length of (that is, number of entries in) the table in 
words 

The vector table has the following format: 

word — Odd address of nonexistent memory error 

word 1 — Memory protect violation 

word 2 — T-bit trap or execution of a BPT instruction 

word 3 — Execution of an lOT instruction 

word 4 — Execution of a reserved instruction 

word 5 — Execution of a non-RSX EMT instruction 

word 6 — Execution of a TRAP instruction 

word 7 — PDP-11/40 floating point exception 

A entry in the table indicates that the task does not want to 
process the corresponding SST. 

Macro Expansion: 



SVTK$ SSTTBL,4 

.BYTE 105. ,3 

.WORD SSTTBL 

.WORD 4 



SVTK$ MACRO DIC, DPB SIZE=3 WORDS 
ADDRESS OF SST TABLE 
SET TABLE LENGTH=4 WORDS 
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Local Symbol Definitions: 

S.VTTA — Table address (2) 

S.VTTL — Table length (2) 
DSW Return Codes: 

IS. sue — Successful completion 

lE.ADP — part of the DPB or table is out of the issuing task's 
address space 

lE.SDP — Die or DPB size is invalid 



■fl^^^^sfe 
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6.3.70 Unmap Address Window 

The Unmap Address Window directive unmaps a specified window. After 
the window has been unmapped, references to the corresponding virtual 
addresses are invalid and cause a processor trap to occur. 

FORTRAN Call: 

CALL UNMAP (iwdb[,ids]) 

iwdb = An 8-word integer array containing a Window Definition 
Block (see Section 3.5.2.2) 

ids = Directive status 

Macro Call: 

UMAP$ wdb 

wdb = Window Definition Block address 

Macro Expansion: 

UMAP$ WDB ADR 

.BYTE 12 3., 2 ;UMAP$ MACRO DIG, DPB SIZE=2 WORDS 

.WORD WDBADR ;WDB ADDRESS 

Window Definition Block Parameters: 

Input parameters 

Array 

Element Offset 

iwdb(l) W.NID — ID of the window to be unmapped 
bits 0-7 

Output para me ters 

iwdb(7) W.NSTS — Bit settings^ in the window status word: 

WS.UNM — 1 if the window was 
successfully unmapped 

Local Symbol Definitions: 

U.MABA — Window Definition Block address (2) 
DSW Return Codes: 

IS. sue — Successful completion 

IE. ITS — The specified address window is not mapped 

lE.NVW — Invalid address window ID 



1 FORTRAN programmers should refer to Section 3.5.2 to determine the 
bit values represented by the symbolic names described. 
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lE.ADP — DPB or WDB out of range 
lE.SDP — DIG or DPB size is invalid 



iff"' "'^w\ 
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6.3.71 Unstop Task 

The Unstop Task directive unstops the specified task which has stopped 
itself via either the Stop or Receive Data Or Stop directive. It does 
not unstop tasks stopped for event flag(s) or tasks stopped for 
buffered I/O. If the Unstop directive is issued to a task previously 
stopped via the Stop or Receive Or Stop directive while at task state, 
and the task is presently at AST state, the task only becomes 
unstopped when it returns to task state. 

The Unstop directive can be issued by a nonpr ivileged task. It is 
considered the responsibility of the unstopped task to determine if it 
has been validly unstopped. 

FORTRAN Call: 

CALL USTP (rtname, [ids] ) 

rtname = Name of task to be unstopped 

ids = Integer to receive directive status information 

Macro Call: 

USTP$ tname 

tname = Name of task to be unstopped 

Macro Expansion: 

USTP$ ALPHA 

.BYTE 133., 3 ; USTP$ MACRO DIC, DPB SIZE=3 WORDS 

.RAD50 ALPHA ;NAME OF TASK TO BE UNSTOPPED 

Local Symbol Definitions: 

U.STTN — Task name (4) 
DSW Return Codes: 

IS. sue — Successful completion 

IE. INS — The specified task is not installed in the system 

IE. ACT — The specified task is not active 

IE. ITS — The specified task is not stopped, or it is stopped 
for event flag(s) or buffered I/O 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 

lE.SDP — DIC or DPB size is invalid 
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VRCD$ 

6.3.72 Variable Receive Data 

The Variable Receive: Datai directive instructs the system to dequeue a 
variable-length data block for the issuing task; the data block has 
been queued (FIFO) for the task via a Variable Send Data directive. 
When a sender task is specified, only data sent by the specified :ask 
i s received . 

Buffer size can be 256. ; ;words maxiiriurn. If no buffer size is 
specified, the buffer size is 13. words. If a buffer size greater 
than 25G. is specified, an lE.IBS error^ is returned. 



A 2-word sender task naroe (in Radix-SO form) and the data block are 
returned in the specified buffer, with the task name in the first two 
words. 

Variable-length data blocks are transferred fron the sending task to 
the receiving taskyby means of buffers in the secondary pool. 

FORTRAN Call: 

CALL VRCD ( [task] >bufadr,tbuflen] , [ids] ) 

task s- sender : task name 



buf = Address of buffer; to: receive the sender task name 
.■■■■-ind-data.: ■:■;■■. ■ 

buflen fr^ Length: of ^buffer ^^^ 

ids r" Integer tq receive the directive status word 
Macro Call: 

VRCD$ [task] ,bufadr[, buflen] 

task *:• sbn<ier :;task name : ::■; 

bufadr =:, Buffer address _ 

buflen =»; Buffer size/in words; " 

Macro Expansion: :::;; ' 

VRCD$ SNDTSK ,DATBUF,BUFSIZ 

.BYTE 75i;:6 ■ ; :; ;VftCP$:MAeRO DIC, DPB SIZE=6 WORDS 

.RAD50 /SNDTSK/ : fSENDER TASK NAME 

.WORD DATBOF : /ADDRESS OF DATA BUFFER 

.WORD BUFjSiZ /BUFFER SIZE 

Local Symbol Definitions: 

R.VDTN — Sender task name {4J 

R.VDBA — Buffer address (2:); ;:; 

R.VDBL -- Buffer; length (2) 

R.VDTI -- Reserved '(.2):- ■'■':.:■■■■' :':^:\:: 0mt. 
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DSW Return Codes: 

IS. sue — Successful completion 

IE. IMS -- Specified task not installed 

IE. ITS — No data in task's receive queue 

lE.RBS — Receive buffer is too small 

IE. IBS — Invalid buffer size specified (greater than 255.) 

lE.ADP — Part of the DPS or buffer is out of the issuing 
task's address space 

lE.SDP -- Die or DPB size is invalid 
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6.3.73 Variable Receive Data Or Stop 

The Variable Receive Data Or Stop directive instructs the system to 
dequeue a variable-longth:data block for the issuing task; the Jata 
block has aeon queued (FIFO) fpr the task via a Variable Send Data 
directive. If there is; no such packet to be dequeued, the issuing 
task is stopped. In this ease, ahother task (the sender task) is 
expected to issue an Unstop directive after sending the data, when 
stopped in this manner, the: ^directivev status returned is IS. SET, 
indicating that the task :;was stopped and that no data has been 
receivea; however, since the task must be unstopped in order to see 
this status, the task can now reissue the Variable Receive Data Or 
Stop directive to actually -receive the data packet. 

When a sender task is specified ,; only data sent by the specified cask 
is received . 

Buffer size can be 256. :Words: maximum. If no buffer size is 
specified, the buffer size is 13. : swords. If a buffer size greater 
than 256. is specified, an lE.IBS error is returned. 

A 2-word sender task name (;i;n:: Radix-50 form) and the data block are 
returned in the specif ied;;buffer, with the task name in the first two 
words. 

Variable-length data blocks -are transferred from the sending task to 
the receiving task by means of buffers in the secondary pool. 

FORTRAN Call: 

CALL VRCS ( [task] ,bufa:di:,[bufienj:, [ids] ) 

task = Sender task name : 



buf = Address -df: buffer: to receive the sender task name 
and data: '■ 

buflen = Length of buffer :; 

ids = Integer :to receive: the directive status word ^^^ 

^acro Call : 

VRCS$ [task] ,bufadr[,buflen) ;■ ^ 

task = Sender task liame;: 

bufadr = Buffer address : 

buflen = Buffer -size in Words 



lYacro Expansion; 



VRCS$ SNDTSK,DATSUy,BUFSi;Z ■ i;:::; 

.BYTE 139., 6 ;VRC^$ MACRO DIC, DPB S1ZE=6 WORDS 

.RAD50 /SNDTSK/ ;SENDER TASK NAME 

.WORD DATBUF :: : : ; AbDRESa OF DATA BUFFER 

.WORD BUFSIZ ; :::- :;6UFFER SIZE 



.^^r^S^ffSt 
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Local Symbol Definitions: 

R.VSTN -- Spnder task name (4) 

R.VGB/v — Emffer address (2) 

R.VSBL -- B'jiCer length (2) 

R.VSTI -- Reserved (2) 
DSW Return Codes: 

It^.dUC — Si;t:ceSGfuL completion 

IE. INS -- Specified task not installed 

IE. RES -- Receive buffer is too -iinali 

IE. IBS -- Invalid buffer size specified (greater than 255.) 

lE.ADl' -- Piirt of tne DPB or buffer is out of the issuing 
tflSK's address space 

IE. SOP — Die or DPB size is invalid 
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6. 3.74 Variable Receive Data Or Exit 

The Variaible Receive Data Or Exit directive instructs the system to 
dequejeA a -variable-length data block for the issuing task; the data 
bloci? has been gueued (FIFO) for the taskvia a Variable Send Data 
directive.; Wh^^n/a sender task is specified^ only data sent by the 
specified task is received. 

A 2-worc3 sender task name (in Radix-50 form) and the data block are 
returned iin the specified buffer, with the task name in the first two 
words.;- 

If no data; has been sent, a task exit occurs. To prevent the possible 
loss of send; data packets, the user should not rely on I/O rundown to 
take care pf any outstanding I/O or open files; the task should 
assume :this: responsibil ity. : 

Buffer; size ;can: be; 256. words maximum. If no buffer size is 
specified, ; the ; buffer size is 13. words. ; If a buffer size greater 
than 256. vis specif ied, an IE. IBS error is returned. 

Variable-length ;data blocks are transferred ■ from the sending task to 
the receiving task by means of buff ers in the ; secondary pool. 

FORTRAN -call:: ■■;!; ; ■ 

CALL VRGx;( [task] ,bufadr, [buf len] ,, [ids] ) 



task: 



Sender task name 



bijf: : - Address of buffer to receive the sender task name 
.;■■■■;: and -data ^- ■;.■■■':;■.:■■ 



'■[■■ buflen = Length of buffer ; 

ids ;= ; Integer to receive the directive status word 

Macro Call^:' ■ 

VRCX$:. : ;:;; [task] ,bufadr[>buflen] v 

task :; = Sender task name 

bufadr= Buffer address ; 

;■;, buf lien :=; Buf jteir size in words 

Macro Expansion: 

VRCX$:; ;SNDTSK^DATBUF,BUFSiz^ 
.Ey:TE ;; 7;7.,€ ;VRCX$ MACRO Die, DPB SIZE=6 WORDS 
.RAD50 /SNDTSK/ : ; SENDER TASK NAME 
.WORD ; DATBUF : ;ADDRESS OF DATA BUFFER 
.WORD > ; BUFSIZ ■'' ; BUFFER SIZE 

Local Symbol Definitions: 

RiVXTN V --^:; Sender task name (4) 

R.VXBA--'-BLiffer address (2) 



j^ff^li 
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R.VXBL -- Buffer lenyt]i (2) 

R.VXTI — Reserved (2) 

DSW Return Codes: 

IS. sue — Successful completion 

IE. INS -- Specified task not installed 

lE.RBS — Receive buffer is too small 

IE, IBS — Invalid bjffer size specified (greater than 25i.) 

lE.ADP — Peirt of the DPB or buffer is out of the issuing 
task's address space 

lE.SDP -- DEC or DP3 size i"? invnIiiH 
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VSDAS 



^^^^ 



6.3.75 Variable Send Data 

The Variable Send Data directive instructs the system to queue a 
variable-length data block for the specified task to receive. 

Buffer size can be 256. words naximuin. If no buffer size is 
specified, the buffer size is 13. words. If a buffer size greater 
than 256. is specified, an IE. IBS error is returned. 

When an event flag is specified, a significant event is declared if 
the directive is successfully executed, and the indicated event flag 
is set for the sending task. 

Variable-length data blocks are transferred from the sending task to 
the receiving task by means of buffers in the secondary pool. 

FORTRAN' Call: 

CALL VSDA ( [tasKj ,bufadr, [buflen] , [efn] , [idti] ) 

task = Receiver task nana 

buf = Address of buffer to receive the receiver task 
name and data 

buflen = Length of buffer 

efn = Event flag number 

ids = Integer to receive the directive status word 
Macro Call: 

VSDA$ [task] ,bufadr[, buflen] [,efn] 

task = Receiver task name 

bufadr = Buffer address 

buflen = Buffer size in words 
Macro Expansion: 



J^S^^ 



VSDA$ 


RECTGK,D 


.BVTE 


71. ,8 


.RAD50 


/RECTSK/ 


.WORD 


DATBUF 


.WORD 


4 


.WORD 


BUFSIZ 



VEDA$ MACRO DIG, DPB SIZE=8 WORDS 
RECEIVER TASK NAME 
ADDRESS OF DATA BUFFER 
EVENT FLAG 4 
BUFFER SIZE 



Local Symbol Definitions: 

S.DATN -- Sender task name (4) 

S.DABA — Buffer address (2) 

S.DAEF — Event flag number (2) 
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S.DA3L — Buffer length (2) 

S.DATI — hesorvod (2) 

DSW Return Codes: 

IS. sue -- Successful coinpleLlon 

lE.UPN -- Insufficient dynamic storage 

IE. INS — Specified task not installed 

IE. IBS -- Invalid buffer size specified (greater than 2'jlj.) 

IL'.IEF — Invalid event flag nunDer 

lE.ADP — Part of the DPI3 or buffer is out of the issuing 
task's address space 

lE.SDP -- Die or DPB size is invalid 
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WSIG$S 



jfli^^^Hfc^ 



6.3.76 Wait For Significant Event ($S form recommended) 

The Wait For Significant Event directive is used to suspend the 
execution of the issuing task until the next significant event occurs. 
It is an especially effective way to block a task that cannot continue 
because of a lack of dynamic memory, since significant events 
occurring throughout the system often result in the release of dynamic 
memory. The execution of a Wait For Significant Event directive does 
not itself constitute a significant event. 

FORTRAN call: 

CALL WFSNE 
Macro Call: 

WSIG$S [err] 

err = Error routine address 
Macro Expansion: 



WSIG$S ERR 

MOV {PC)+,-(SP) 

.BYTE 49. ,1 

EMT 377 

BCC .+6 

JSR PC, ERR 



;PUSH DPB ONTO THE STACK 

;WSIG$S MACRO DIC, DPB SIZE=1 WORD 

;TRAP TO THE EXECUTIVE 

; BRANCH IF DIRECTIVE SUCCESSFUL 

/OTHERWISE, CALL ROUTINE "ERR" 



Local Symbol Definitions: 

None 
DSW Return Codes: 

IS. sue = Successful completion 

lE.ADP = Part of the DPB is out of the issuing task's address 
space 

lE.SDP = DIC or DPB size is invalid 
Notes: 

1. If a directive is rejected for lack of dynamic memory, this 
directive is the only technique available for blocking task 
execution until dynamic memory may again be available. 

2. The wait state induced by this directive is satisfied by the 
first significant event to occur after the directive has been 
issued. The significant event that occurs may or may not be 
related to the issuing task. 

3. Because this directive requires only a 1-word DPB, the $S 
form of the macro is recommended. It requires less space and 
executes with the same speed as the DIR$ macro. 
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4. Significant events include the following: 

• I/O completion 

• Task exit 
Execution of a Send Data directive 
Execution of a Send By Reference directive 
Execution of an Alter Priority directive 






Removal of an entry from the clock queue (for instance, 
resulting from the execution of a Mark Time directive or 
the issuance of a rescheduling request) 

Execution of a Declare Significant Event directive 



• Execution of the round-robin scheduling algorithm at the 
end of a round-robin scheduling interval 
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WTLO$ 

6.3.11 Walt For Logical OR Of Event Flags 

The Wait For Logical OR Of Event Flags directive instructs the system 
to block the execution of the issuing task until the Executive sets 
the indicated event flags from one of the following groups: 

GR — Flags 1-16 

GR 1 — Flags 17-32 

GR 2 — Flags 33-48 

GR 3 — Flags 49-64 

GR 4 — Flags 65-80 

GR 5 — Flags 81-96 

The task does not block itself if any of the indicated flags are 
already set when the task issues the directive. See Notes below, 

FORTRAN Call: 

CALL WFLOR (ef nl ,ef n2 , , . .ef nn) 

efn = List of event flag numbers taken as the set of flags to 
be specified in the directive 

Macro Call : 

WTLO$ grp,msk 

grp = Desired group of event flags 

msk = A 16-bit flag mask word 

Macro Expansion: 

WTLO$ 2,160003 

,BYTE 43., 3 ;WTLO$ MACRO DIC, DPB SIZE=3 WORDS 

.WORD 2 ; FLAGS SET NUMBER 2 (FLAGS 33:48.) 

.WORD 160003 /EVENT FLAGS 33,34,46,47 AND 48. 

Local Symbol Definitions: 

None 
DSW Return Codes: 

IS. sue — Successful completion 

lE.lEF — No event flag specified in the mask word or flag 
group indicator other than 0, 1, 2, 3, 4, or 5 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 

lE.SDP — DIC or DPB size is invalid 
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DIRECTIVE DESCRIPTIONS 



There is a one-to-one 

word and the 

group 1 were 

correspond 

forth. 

The Executive does not arbitrarily clear event flags when 
Wait For conditions are met. Some directives (Queue I/O 
Request, for example) implicitly clear a flag; otherwise, 
they must be explicitly cleared by a Clear Eveht Flag 
directive. 

The grp operand must always be of the form n regardless of 
the macro form used. In all other macro calls, numeric or 
address values for $S form macros have the form: 

#n 

For WTLO$S this form of the grp argument would be: 



The argument list specified in the FORTRAN call must contain 
only event flag numbers that lie within one event flag group. 
If event flag numbers are specified that lie in more than one 
group, or if an invalid event flag number is specified, a 
fatal FORTRAN error is generated. 
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WTSE$ 

6.3.78 Wait For Single Event Flag 

The Wait For Single Event Flag directive instructs the system to block 
the execution of the issuing task until the indicated event flag is 
set. If the flag is set at issuance, task execution is not blocked. 

FORTRAN Call: 

CALL WAITFR (efn[,ids]) 

efn = Event flag number 

ids = Directive status 

Macro Call: 

WTSE$ efn 

efn = Event flag number 

Macro Expansion: 

WTSE$ 52. 

•BYTE 41., 2 ;WTSE$ MACRO DIC, DPB SIZE=2 WORDS 

.WORD 52. ; EVENT FLAG NUMBER 52. 

Local Symbol Definitions: 

W.TSEF — Event flag number (2) 
DSW Return Codes: 

IS. sue — Successful completion 

lE.IEF — Invalid event flag number (EFN>64 or EFN<1) 

lE.ADP — Part of the DPB is out of the issuing task's address 
space 

lE.SDP — DIC or DPB size is invalid ^^fc* 
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Abort Task ABRT$ 

FORTRAN Call: 

CALL ABORT (tsk[,ids]) 
tsk == Task name 
ids == Directive status 
Macro Call: 

ABRT$ tsk 

tsk == Task name 

Alter priority ALTP$ 

FORTRAN Call: 

CALL ALTPRI ( [ tsk] , [ ipr i] [ , ids] ) 

tsk = Active task name 

ipri == 1-word integer value equal to the new priority, from 1 
to 250 (decimal) 

ids = Directive status 

Macro Call: 

ALTP$ [tsk] [,pri] 

tsk = Active task name 

pri = New priority, from 1 to 250 (decimal) 

Assign LUM ALUN$ 

FORTRAN Call: 

CALL ASNLUN (lun ,dev ,unt [ , ids] ) 
lun = Logical unit number 
dev = Device name (format 1A2) 
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unt = Device unit number 

ids = Directive status ■^^] 
Macro Call: 

ALUN$ lun,dev,unt 

lun = Logical unit number 

dev = Device name (two characters) 

unt = Device unit number 

AST Service Exit ($S form recommended) ASTX$S 

FORTRAN Call: 

Neither the FORTRAN language nor the ISA standard permits direct 
linking to system-trapping mechanisms; therefore, this directive 
is not available to FORTRAN tasks. Ji^k 

Macro Call: 

ASTX$S [err] 

err = Error routine address 

Attach Region ATRG$ 

FORTRAN Call: i^lli 

CALL ATRG (irdb[,ids]) 

irdb = An 8-word integer array containing a Region Definition 
Block (see Section 3.5.1.2) 

ids = Directive status 

Macro Call: 

ATRG$ rdb f^ilfe 

rdb = Region Definition Block address 

Connect To Interrupt Vector CINT$ 

FORTRAN Call: 

Not supported 
Macro Call: 

CINT$ vec ,base,isr ,edir ,psw,ast 

vec = Interrupt vector address — Must be in the range 60(8) 
to highest vector specified during SYSGEN, inclusive, 
and must be a multiple of 4 

base = virtual base address for kernel APR 5 mapping of the JiHii 
ISR, and enable/disable interrupt routines fsfPl 



A- 2 



DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL 



isr = virtual address of the ISR, or to disconnect from the 
interrupt vector 

edir = virtual address of the enable/disable interrupt routine 

psw = Low-order byte of the Processor Status Word to be 
loaded before entering the ISR 

ast = Virtual address of an AST routine to be entered after 
the fork-level routine queues an AST 



Clear Event Flag 

FORTRAN Call: 

CALL CLREF (efn[,ids]) 

efn = Event flag number 
ids = Directive status 
Macro Call: 

CLEF$ efn 

efn = Event flag number 

Cancel Mark Time Requests 

FORTRAN Call: 

CALL CANMT ( [ef n ,ast] , ids) 
ids = Directive status 
efn = Event flag number 
ast = Mark time AST address 

Macro Call: 

CMKT$ [efn, ast, err] 

efn = Event flag number 
ast = Mark time AST address 
err = Error routine address 



CLEF$ 



CMKT$ 



Connect 

FORTRAN Call: 

CALL CNCT (rtname, [iefn] , [iast] , [iesb] , [iparm] , [ids] ) 
rtname = Name of the offspring task to be connected 



CNCT$ 



iefn 



Event flag to be set when the offspring task exits 
or emits status 
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last = Address o'f an AST routine to be called when the 
offspring task exits or emits status 

iesb = Address of an 8-word status block to be written when 
the offspring task exits or emits status 

word — Offspring task exit status 

word 1-7 — Reserved 

iparm = Address of a word to receive the status block 
address when an AST occurs 

ids = Integer to receive the Directive Status Word 

Macro Call: 

CNCT$ tname, [efn] , [east] , [esb] 

tname = Name of the offspring task to be connected 

efn = The event flag to be cleared on issuance and set 
when the offspring task exits or emits status 

east = Address of an AST routine to be called when the 
offspring task exits or emits status 

esb = Address of an 8-word status block to be written when 
the offspring task exits or emits status 

word — Offspring task exit status 

word 1-7 — Reserved 

Create Address Window CRAW$ 

FORTRAN Call: 

CALL CRAW (iwdb[,ids]) 

iwdb = An 8-word integer array containing a Window Definition 
Block (see Section 3.5.2.2) 

ids = Directive status 

Macro Call: 

CRAW$ wdb 

wdb = Window Definition Block address 

Create Group Global Event Flags CRGF$ 

FORTRAN Call: 

CALL CRGF ( [group] ,[ ids] ) 

group = Group number for the flags to be created - If not 
specified, the task's protection UIC (H.CUIC+1) in 
the task's header is used 
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ids = Integer to receive the Directive Status Word 

Macro Call: 

CRGF$ [group] 

group = Group number for the flags to be created - If not 
specified, the task's protection UIC (H.CUIC+1) in 
the task's header is used 

Create Region CRRG$ 

FORTRAN Call; 

CALL CRRG (irdb[,ids]) 

irdb = An 8-word integer array containing a Region Definition 
Block (see Section 3.5.1.2) 

ids = Directive status 

Macro Call: 

CRRG$ rdb 

rdb = Region Definition Block address 



Create virtual Terminal CRVT$ 

FORTRAN Cal-l: 

CALL CRVT ( [iiast] [,ioast] [ ,iaast] [,iitilen] , iparm [ , ids] ) 

iiast = AST address at which input requests fron offspring 
tasks are serviced 

ioast = AST address at which output requests from offspring 
tasks are serviced 

iaast = AST address at wnich the parent task nay be notified 
of the completion of successful offspring attach and 
detach requests to the virtual terminal unit 

imlen = Maximum buffer length allowed for offspring I/O 
requests 

iparm = Address of 3-word buffer to receive information from 
the stack when an AST occurs 

ids = Integer to receive the Directive Status Word 

Macro Call: 

CRVT5 [iast] [, oast] [ ,adst] [mien] 

last = AST address at which input requests from offspring 
tasks are serviced 

oast = AST address at which output requests from offspring 
tasks are serviced 
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aast = AST address at which the parent task may be notified 
of the completion of successful offspring attach and 
detach requests to the virtual terminal unit — If 
this parameter is not specified, no notification of 
attaches and detaches are returned to the parent 
task 

mien = Maximum buffer length allowed for offspring I/O 
requests 



Cancel Time Based Initiation Requests CSRQ$ 

FORTRAN Call: 

CALL CANALL (tsk[,ids]) 
tsk = Task name 
ids = Directive status 
Macro Call: 

CSRQ$ tsk 

tsk = Task name 

Declare Significant Event ($S form recommended) DECL$S 

FORTRAN Call: 

CALL DECLAR ( [ ,ids] ) 

ids = Directive status 
Macro Call: 

DECL$S [,err] 

err = Error routine address 

Disable AST Recognition ($S form recommended) DSAR$S 

FORTRAN Call: 

CALL DSASTR [ (ids) ] 

ids = Directive status 
Macro Call: 

DSAR$S [err] 

err = Error routine address 

Disable Checkpointing ($S form recommended) DSCP$S 

FORTRAN Call: 

CALL DISCKP 
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Macro Call: 

DSCP$S [err] 

err = Error routine address 

Detach Region °'^^°^ 

FORTRAN Call: 

CALL DTRG (irdb[,ids]) 

irdb = An 8-word integer array containing a Region Definition 
Block (see Section 3.5.1.2) 

ids = Directive status 
Macro Call; 

DTRG$ rdb 

rdb = Region Definition Block address 

Eliminate Address Window ELAW$ 

FORTRAN Call: 

CALL ELAW (iwdb[,ids]) 

iwdbi = An 8-word integer array containing a Window 
Definition Block (see Section 3.5.2.2) 

ids = Directive status 
Macro Call: 

ELAW$ wdb 

wdb = Window Definition Block address 

Eliminate Group Global Event Flags ELGF$ 

FORTRAN Call: 

CALL ELGF ( [group] ,[ ids] ) 

group = Group number of flags to be eliminated 
ids = Integer to receive the Directive Status Word 
Macro Call: 

ELGF$ [group] 

group = Group number of flags to be eliminated 
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Eliminate Virtual Terminal ELVT$ 

FORTRAN Call: ;•: ' ; \ 
CALL ELVT { iUnura [ , ids] ) 

iunum = yirtual terminal unit number 

ids = ;;;;Integer to receive the Directive Status Word 
Macro Call: 

ELVT$ unura/; . ■ 

unum =;Uriit number of the virtual terminal to be eliminated 



EMST$ 



Emit Status 

FORTRAN Call: 

CALL EMST ( L ttname] , i statiiS [ , ids] ) \./. 

rtname = ; iiame;pf task connected to issuing task to which the 
iStatus is to be emitted; 

istatus = yl6-bit quantity to be returned to the connected task 
ids = ■integer to receive the Directive status Word 
Macro Call : 

EMST$ [tname]:,status 

tname = Name of a task conhiected to the issuing task to 
Which the status is to be emitted 

status = .ie^bit quantity to be returned to the connected task 



Enable AST Recognition ($S form recommended) 

FORTRAN Call: 

CALL ENASTR 
Macro Call: 

ENAR$S [err] 

err = Error routine address 



ENAR$S 



^P^^fll^ 



-^^ 



^^^^fk 



Enable Checkpointing ($S form recommended) 

FORTRAN Call: 

CALL ENACKP 
Macro Call: 

ENCP$S [err] 

err = Error routine address 



ENCP$S 
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Exit If EXIF$ 

FORTRAN Call: 

CALL EXITIF {efn[,ids]) 
efn = Event flag number 
ids = Directive status 
Macro Call: 

EXIF$ efn 

efn = Event flag number 

Task Exit ($S form recommended) EXIT$S 

FORTRAN Call: 

STOP 

or 
CALL EXIT 

Macro Call: 

EXIT$S [err] 

err =■ Error routine address 

Exit With Status EXST$ 

FORTRAN Call: 

CALL EX£>T (i Status) 

istatus = 16-bit quantity to be returned to parent task 
Macro Call: 

EXST$ status 

status = 16-bit quantity to be returned to parent task 

Extend Task EXTK$ 

FORTRAN Call: 

CALL EXTTSK { [ inc] [ , ids] ) 

inc = A positive or negative number equal to the number of 
32-word blocks by which the task size is to be extended 
or reduced - If omitted, task size defaults to 
installed task size 

ids = Directive status 

Macro Call: 

EXTK$ [inc] 
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Inc = A positive or negative number equal to the number of 
32-word blocks by which the task is to be extended or 
reduced - If omitted, task size defaults to installed 
task size 

Get LUN Information GLUN$ 

FORTRAN Call: 

CALL GETLUN (lun ,dat [ , ids] ) 

lun = Logical unit number 

dat = 6-word integer array to receive LUN information 

ids = Directive status 

Macro Call: 

GLUN$ lun,buf 

lun = Logical unit number 

buf = Address of 6-word buffer that will receive the LUN 
information 

Get MCR Command Line GMCR$ 

FORTRAN Call: 

CALL GETMCR (buf[,lds]) 

buf = 80-byte array to receive command line 
ids = Directive status 
Macro Call: 
GMCR$ 

Get Mapping Context GMCX$ 

FORTRAN Call: 

CALL GMCX {imcx[,ids] ) 

imcx = An integer array to receive the mapping context. The 
size of the array is 8*n+l, where n is the number of 
window blocks in the task's header - The maximum size 
is 8*8+1=65. 

ids = Directive status 

Macro Call: 

GMCX$ wvec 

wvec = The address of a vector of n Window Definition Blocks; 
n is the number of window blocks in the task's header 
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Get Partition Parameters GPRT$ 

FORTRAN Call: 

CALL GETPAR ( [pr t] ,buf [ , ids] ) 
prt = Partition name 

buf = A 3-word integer array to receive partition parameters, 
ids = Directive status 
Macro Call: 

GPRT$ [prt] ,buf 

prt = Partition name 

buf = Address of 3-word buffer 

Get Region Parameters GREG$ 

FORTRAN Call: 

CALL GETREG { [ r id] ,buf [ , ids] ) 
rid = Region id 

buf = 3-word integer array to receive region parameters 
ids = Directive status 
Macro Call: 

GREG$ [rid] [,buf] 
rid = Region id 
buf = Address of 3-word buffer 

Get Sense Switches ($S form recommended) GSSW$S 

FORTRAN Call: 

CALL READSW (isw) 

isw = Integer to receive the console switch settings 
Macro Call: 

GSSW$S [err] 

err = Error routine address 

Get Time Parameters GTIM$ 

FORTRAN Call: 

FORTRAN provides several subroutines for obtaining the time in a 
number of formats. See the IAS/RSX-11 FORTRAN-IV User's Guide or 
the FORTRAN IV-PLUS User's Guide. 
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Macro Call: 

GTIM$ buf "^ 

buf = Address of 8-word buffer 

Get Task Parameters GTSK$ 

FORTRAN Call: 

CALL GETTSK (buf[,ids]) 

buf = 16-word integer array to receive the task parameters 
ids = Directive status 
Macro Call: 

GTSK$ buf 

buf = Address of 16-word buffer 

Inhibit AST Recognition ($S form recommended) IHAR$S 

FORTRAN Call: 

CALL INASTR [ (ids) ] 

ids = Directive status 
Macro Call : 

IHAR$S [err] 

err = Error routine address 

Map Address Window MAP$ 

FORTRAN Call: 

CALL MAP (iwdb[,ids]) ^^ 

iwdb = An 8-word integer array containing a Window Definition 
Block (see Section 3.5.2.2) 

ids = Directive status 

Macro Call: 

MAP$ wdb 

wdb = Window Definition Block address 



^^^k 
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Mark Time "'^^'''^ 

FORTRAN Call: 

CALL MARK (ef n , tmg ,tnt [ , ids] ) 

efn == Event flag number 

tmg == Time interval magnitude 

tnt == Time interval unit 

ids == Directive status 

The ISA standard call for delaying a task for a specified time 
interval is also included: 

CALL WAIT (tmg, tnt, ids) 

tmg = Time interval magnitude 
tnt = Time interval unit 
ids = Directive status 
Macro Call: 

MRKT$ [efn] ,tmg,tnt[,ast] 
efn = Event flag number 
tmg = Time interval magnitude 
tnt = Time interval unit 
ast = AST entry point address 

Queue I/O Request QI05 

FORTRAN Call: 

CALL QIO (fnc,lun, [efn] , [pri] , [isb] , [prl] [,ids] ) 

fuc = I/O function code 

lun = Logical unit number 

efn = Flag number 

pri = Priority; ignored, but must be present 

isb = 2-word integer array to receive final I/O status 

prl = 6-word integer array containing device-dependent 
parameters to be placed in parameter words 1 through 6 
of the Directive Parameter Block (DPB) 

ids = Directive status 
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Macro Call : 

QIO$ fnc,lun, [efn] , [pri] , [isb] , [ast] [,prl] 

fnc = I/O function code 

lun = Logical unit number 

efn = Event flag number 

pri = Priority; ignored, but must be present 

isb = Address of I/O status block 

ast = Address of AST service routine entry point 

pri = Parameter list of the form <P1,...P6> 

Queue I/O Request And Wait QIOW$ 

FORTRAN Call: ^f^lh 

CALL WTQIO (fnc, lun, efn, [pri] , [isb] , [pri] [, ids]) 
fnc = I/O function code 
lun = Logical unit number 
efn = Event flag number 

pri = Priority; ignored, but must be present 
isb = 2-word integer array to receive final I/O status 

pri = 6-word integer array containing device dependent 
parameters to be placed in parameter words 1 through 6 
of the DPS 

ids = Directive status 

Macro Call: 

QIOW$ fnc, lun, efn, [pri] , [isb] , [ast] [,prl] 

fnc = I/O function code 

lun = Logical unit number 

efn = Event flag number 

pri = Priority; ignored, but must be present 

isb = Address of I/O status block 

ast = Address of AST service routine entry point 

pri = Parameter list of the form <P1,...P6> 
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Receive Data Or Stop 

FORTRAN Call: 

CALL RCST ( [rtname] ,ibuf [ ,ids] ) 

rtname = Name of task from which data is to be received 
ibuf 



RCST$ 



ids 
Macro Call: 
RCST$ 
tname 



= Address of 15-word buffer to receive the sender task 
name and data 

Integer to receive the Directive Status Word 



[tname] ,buf 

= Name of task from which data is to be received — If 
not specified, data may be received from any task 



buf = Address of a 15-word buffer to receive the sender 
task name and data 



Receive Data 

FORTRAN Call: 

CALL RECEIV ( tsk ,buf [ , , ids] ) 
tsk = Sender task name 

buf = 15-word integer array for received data 
ids = Directive status 
Macro Call: 

RCVD$ tsk, buf 

tsk = Sender task name 

buf = Address of 15-word buffer 

Receive Data Or Exit 

FORTRAN Call: 

CALL RECOEX ( tsk ,buf [ , , ids] ) 
tsk = Sender task name 

buf = 15-word integer array for received data 
ids = Directive status 
Macro Call: 

RCVX$ tsk, buf 

tsk = Sender task name 

buf = Address of 15-word buffer 



RCVD$ 



RCVX$ 
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DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL 



Read All Event Flags RDAF$ 

FORTRAN Call: 

Only a single event flag can be read by a FORTRAN task. The call 
is: 

CALL READEF (efn[,ids]) 

efn = Event flag number (1-64.) 

ids = Directive status 
Macro Call: 

RDAF$ buf 

buf = Address of 4-word buffer 

Read Extended Event Flags RDXF$ 

FORTRAN Call: 

Only a single event flag can be read by a FORTRAN task. The call 
is : 

CALL RDADEF (efn [, ids]) 

efn = Event flag number (1-96.) 

ids = Directive status 
Macro Call: 

RDXF$ buf 

buf = Address of 6-word buffer 

Remove Affinity ($S form only) RNAF$S 

FORTRAN Call: 

CALL RMAF ( [ids] ) 

ids = Integer to receive the Directive status Word 
Macro Call: 

RMAF$S 



4^^ 



t^^^Tak 



Request Task 

FORTRAN Call: 

CALL REQUES ( tsk , [opt] [ , ids] ) 
tsk = Task name 



RQST$ 



^"'^^^ 
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DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL 

opt = 4-word Integer array 

opt(l) = partition name first half; ignored, but 
must be present 

opt(2) = partition name second half; ignored, but 
must be present 

opt(3) = priority; ignored, but must be present 

opt(4) = User Identification Code 
ids = Directive status 
Macro Call: 

RQST$ tsk, [prt] , [pri] [,ugc,umc] 
tsk == Task name 

prt == Partition name; ignored, but must be present 
pri == Priority; ignored, but must be present 
ugc == UIC group code 
umc == UIC member code 

Receive By Reference RREF$ 

FORTRAN Call: 

CALL RREF ( iwdb, [ isrb] [ , ids] ) 

iwdb = An 8-word integer array containing a Window Definition 
Block (see Section 3.5.2.2) 

isrb = A 10-word integer array to be used as the receive 
buffer 

ids = Directive status 

Macro Call: 

RREF$ wdb 

wdb = Window Definition Block 

Resume Task RSUM$ 

FORTRAN Call: 

CALL RESUME (tsk [, ids]) 
tsk = Task name 
ids = Directive status 
Macro Call; 

RSUM$ tsk 

tsk = Task name 
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DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL 

Run Task RUN$ 

FORTRAN Call: 

CALL RUN (tsk, [opt] , [smg] ,snt, [rrag] , [rnt] [,ids] ) 

tsk = Task name 

opt = 4-word integer array 

opt(l) = partition name first half; ignored, but 
must be present 

opt(2) = partition name second half; ignored, but 
must be present 

opt(3) = priority; ignored, but must be present 

opt(4) = User Identification Code 

smg = Schedule delta magnitude 

snt = Schedule delta unit ' "^ 

rmg = Reschedule interval magnitude 

rnt = Reschedule interval unit 

ids = Directive status 
The ISA standard call for initiating a task is also included: 
CALL START ( tsk , smg , snt , ids) ^Hl^ 

tsk = Task name 

smg = Schedule delta magnitude 

snt = Schedule delta unit 

ids = Directive status 
Macro Call: 

RUN$ tsk, [prt] , [pri] , [ugc] , [umc] , [smg] ,snt[ ,rmg,rnt] 

tsk = Task name 

prt = Partition name; ignored, but must be present 

pri = Priority; ignored, but must be present 

ugc = UIC group code ? 

umc = UIC member code 

smg = Schedule delta magnitude 

snt = Schedule delta unit ^ 

rmg = Reschedule interval magnitude 

rnt = Reschedule interval unit 
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DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL 



Supervisor Call SCAL$S 

FORTRAN Call: 

Not supported 
Macro Call;' 

SCAL$S saddr,caddr 

saddr = Address of the called Supervisor mode routine 

caddr = Address of the completion routine for return to the 
caller 



Send Data SDAT$ 

FORTRAN Calls 

CALL SEND ( tsk ,buf , [ef n] [ , ids] ) 

tsk == Task name 

buf == 13-word integer array of data to be sent 

efn == Event flag number 

ids := Directive status 
Macro Call: 

SDAT$ tsk, buf [, efn] 

tsk = Task name 

buf = Address of 13-word data buffer 

efn = Event flag number 



Send, Request And Connect SDRC$ 

FORTRAN Call: 

CALL SDRC (rtnanie,ibuf [ ,iefn] [ fiast] [,iesb] [,iparmj [ ,ids] ) 

rtnanie = Target task name of the offspring task to be 
connected 

ibuf = Address of 13-word send buffer 

iefn = Event flag to be set when the offspring tas< exits 
or emits status 

last = Address of an AST routine to be called w.ien the 
offspring task exits or emits status 

iesb = Address of an 8-word status block to be written when 
the offspring task exits or emits status 

word — Offspring task exit status 

word 1-7 — Reserved 
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DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL 

iparm = Address of a word to receive the status block 
address when an AST occurs 

ids = Integer to receive the Directive Status Word 

Macro Call: 

SDRC$ tname,buf ,efn,east,esb 

tname = Target task name of the offspring task to be 
connected 

buf = Address of a 13-word send buffer 

efn = The event flag to be cleared on issuance and when the 
offspring task exits or emit status 

east = Address of an AST routine to be called when the 
offspring task exits or emits status 

esb = Address of a 8-word status block to be written when 
the offspring task eicits or emits status 

word — Offspring task exit status 

word 1-7 — Reserved 



Set Event Flag SETF$ 

FORTRAN Call: 

CALL SETEF (efn[,ids]) 

efn = Event flag number 
ids = Directive status 
Macro Call: 

SETF$ efn 

efn = Event flag number 

Specify Floating Point Exception AST SEPA$ 

FORTRAN Call: 

Not supported 
Macro Call: 

SFPA$ [ast] 

ast = AST service routine entry point address 

Specify Parity Error AST SPEA$ 

FORTRAN Call: 

Not supported 
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DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL 



Macro Call: 

SPEA$ [a St] 

ast == AST services routine entry point address 



Suspend ($S form recommended) 
FORTRAN Call! 

CALL SUSPND 
Macro Call: 

SPND$S [err] 

err = Error routine address 



SPND$S 



Specify Power Recovery AST SPRA$ 

FORTRAN Call: 

CALL PWRUP (sub) 

sub = Name of a subroutine to be executed upon power 
recovery. The PWRUP subroutine will effect the 
following: 

CALL sub (no arguments) 

The subroutine is called as a result of a power 
recovery AST, and therefore the subroutine can be 
controlled at critical points by using the DSASTR (or 
INASTR) and ENASTR subroutine calls 

Macro Call: 

SPRA$ [ast] 

ast = AST service routine entry point address 



Spawn 

FORTRAN Call: 



SPWN$ 



CALL SPAWN (rtnarae, [iugc] , [iumc] , [iefn] , [iast] , [iesb] , [iparm] , 
[icmlin] , [icmlen] , [iunit] , [dnam] , [ids] ) 

rtname = Name of the offspring task to be spawned 

iugc = Group code number for the UIC of the offspring task 

iumc = Member code number for the UIC of the offspring task 

iefn = Event flag to be set when the offspring task exits 
or emits status 

iast = Address of an AST routine to be called v/hen the 
offspring task exits or "emits status 
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ids 


Macro Call: 




SPWN$ 




tname 




ugc 




umc 




efn 



DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL 

iesb = Address of an 8-word status block to be written when 
the offspring task exits or emits status, 

word — Offspring task exit status 

word 1-7 — Reserved 

iparm = Address of a word to receive the status block 
address when the AST occurs 

icmlin = Address of a command line to be queued for the 
offspring task 

icmlen = Length of the command line (79. characters maximum) 

iunit = Unit number of terminal to be used as the TI : for 
the offspring task - If tho optional dnam parameter 
is hot &^^ parameter must bo the unit 

naml??f b^^ virtual terminal created by the issuing 
tSiiSk;; if a value of is specified, the TI : of the 
issuing task is propagated 

dnam = Device name mnemonic - If not specified, the vi;rtual 

■•t^si;m;i;nal^::.is;:\used'-a^.:'Ti : 

= Integer to receive the Directive Status Word 



tname, , , [ugc] , [umc] , [efn] , [east] , [esb] , [cmdlin] , [cmdlen] 
, [unum] , [dnam] 

= Name of the offspring task to be spawned 

= Group code number for the UIC of the offspring task 

Member code number for the UIC of the offspring task 

The event flag to be cleared on issuance and set 
when the offspring task exits or emits status 

east = Address of an AST routine to be called when the 
offspring task exits or emits status 

esb = Address of an 8-word status block to be written when 
the offspring task exits or emits status ' 

word — Offspring task exit status 

word 1-7 — Reserved 

cmdlin = Address of a command line to be queued for the 
offspring task 

cmdlen = Length of the command line (maximum length is 79.) 

unum = Unit number of terminal to bo used as the TI : for 
the offspring task - If the optional dnam parameter 
.:;i;^ "n(i.t sp^dif le^^^ parameter must be the unit 
inurab^r^^, 0^^^^ created by the issuing 

i^isk;;^- if a value of is specified the TI: of the 
issuing task is propagated 

dnam = Device name mnemonic - If not specified, the virtual 
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NOTE 

1. If neither unum nor dnam is specified, 
the TI: of the issuing task is 
propagated . 

2. If only unum is specified, TI: is a 
virtual terminal. 

Specify Receive Data AST SRDA$ 

FORTRAN Call: 

Not supported 
Macro Call: 

SRDA$ [ast] 

ast = AST service routine entry point address 

Specify Requested Exit AST SREA$ 

FORTRAN Cal L : 

Not supported 
Macro Call: 

SREA$ [ast] 

ast = AST service routine ortry point address 



Send By Reference SREF$ 

FORTRAN Call: 

CALL SREF ( tsk , [ef n] , iwdb, [ isrb] [ , ids] ) 

tsk = Receiver task name 

efn = Event flag number 

iwdb = An 8-word integer array containing a Window Definition 
Block (see Section 3.5.2.2) 

isrb = An 8-word integer array containing additional 
information 

ids = Directive status 

Macro Call: 

SREF$ task, wdb[ , efn] 

task = Receiver task name 

wdb = Window Definition Block 

efn = Event flag number 
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Specify Receive-By-Reference AST SRRA$ 

FORTRAN Call: 

Not supported 
Macro Call: 

SRRA$ [ast] , 

ast = AST service routine entry point address 

Set Affinity STAF$ 

FORTRAN Call: 

CALL STAF (iaff , [ids] ) 

iaff = Affinity mask word 

ids = Integer to receive Directive Status Word "^l'. 

Macro Call: 

STAF$ [cplub'ub. . .] 

cp = CPU selected (A through D) 

ub = UNIBUS run(s) selected (\i through T) 

Stop For Logical OR Of Event Flags STLO$ .<*%^ 

FORTRAN Call: 

CALL STLOR ( ief 1 , ief 2 , ief 3 , ... ief(n)) 

iefl ... ief(n) = List of event flag numbers 
Macro Call: 

STLO$ grp, msk 

grp = Desired group of event flags 
msk = A 16-bit mask word 

Stop ($S form recommended) STOP$S 

FORTRAN Call: 

CALL STOP ( [ids] ) 

ids = Integer to receive the Directive Status Word 
Macro Call: , 

STOP$S 



A-24 



DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL 

Stop For Single Event Flag STSE$ 

FORTRAN Call: 

CALL STOPFR {iefn[,ids]) 
iefn = Event flag number 

ids == Integer to receive Directive Status Word 
Macro Call: 

STSE$ efn 

efn == Event flag number 

Specify SST Vector Table For Debugging Aid SVDB$ 

FORTRAN Calls 

Not supported 
Macro Call: 

SVDB$ [adr] [,len] 

adr == Address of SST vector table 

len == Length of (that is, number of entries in) table in 
words 

Specify SST Vector Table For Task SVTK$ 

FORTRAN Call: 

Not supported 
Macro Call: 

SVTK$ [adr] [,len] 

adr = Address of SST vector table 

len = Length of (that is, number of entries in) table in 
words 

Unmap Address Window UNMAP$ 

FORTRAN Call: 

CALL UNMAP (iwdb[,ids]) 

iwdb = An 8-word integer array containing a Window Definition 
Block (see Section 3.5.2.2) 

ids = Directive status 

Macro Call: 

UMAP$ wdb 

wdb = Window Definition Block address 
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Unstop USTP$ 

FORTRAN Call: f^%f, 

CALL USTP (rtname[ ,ids] ) 

rtname = Name of task to be unstopped 

ids = Integer to receive directive status information ^ 

Macro Call: 

USTP$ tname 

tname = Name of task to be unstopped ♦ 

Variable Receive Data VRCD$ 

FORTKAN Call: 

CALL VRCD { [task] ,bufadr, [buflen] , [ids] ) j«% 

task = Sender task name 

buf = Address of buffer to receive the sender task name 
and data 

buflen = Length of buffer 

ids = Integer to receive the directive status word 

Macro Call: Ji^ 

VRCD$ [task] ,bufadr[, buflen] 

task = Sender task name 

bufadr = Buffer address 

buflen = Buffer size in words 

Variable Receive Data Or Stop VRCS$ .^li^ 

FORTRAN Call: 

CALL VRCS ( [task] , bufadr, [buflen] , [ids] ) 

task = Sender task name 

buf = Address of buffer to receive the sender task name 

and data * 

buflen = Length of buffer 

ids = Integer to receive the Directive Status Word 



■iB^™^^ffm 
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VRCX$ 



DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL 

Macro Call: 

VUCS$ [task] , buf adr [, buf len] 

tas:< - Sender task namo 

bufadi; = Buffer address 

buflen = Buffer size in words 

Variable Receive Data Or Exit 

FORTRAN Call: 

CALL VRCX ( [task] fbufadr, [buf len] , [ids] ) 
task = Sender task name 

buf = Address of buffer to receive the sender task name 
and data 

buflen = Length of buffer 

ids = Integer to receive the Directive Status Word 

Macro Call: 

VRCX$ [task] , buf adr [, buflen] 

task = Sender task name 

bufadr = Buffer address 

buflen = Buffer size in words 

Variable Send Data VSDA$ 

FORTRAN Call: 

CALL VSDA ( [task] , bufadr , [buf len] , [efn] , ids] ) 

task = Receiver task name 

buf = Address of buffer to receive the sender task name 
and data 

buflen = Length of buffer 

efn = Event flag number 

ids = Integer to receive the Directive Status V'Vord 
Macro Call: 

VSDA:? [task] , bufadr, [buflen] [,efn] 

task = Receiver task name 

bufadr = Buffer address 

buflen = Buffer size in words 

efn = Event flag number 
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Wait For Significant Event ($S form r<scommended) 

FORTRAN Call: 

CALL WFSNE 
Macro Call: 

WSIG$S [err] 

err = Error routine address 



WSIG$S 



Wait For Logical OR Of Event Flags WTLO$ 

FORTRAN Call: 

CALL WFLOR (ef nl ,ef n2 , . . .ef nn) 

efn = List of event flag numbers taken as the set of flags to 
be specified in the directive 

Macro Call: 

WTLO$ grp,msk 

grp = Desired group of event flags 

msk = A 16-bit octal mask word 



Wait For Single Event Flag 

FORTRAN Call: 

CALL WAITFR (efn[,ids]) 
efn = Event flag number 
ids = Directive status 
Macro Call: 

WTSE$ efn 

efn = Event flag number 



WTSE$ 



7*% 



mf^ 
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APPENDIX B 
STANDARD ERROR CODES 



The symbols listed below are associated with the directive status 
codes returned by the RSX-llM/M-PLUS Executive. They are determined 
(by default) at task-build time. To include these in a MACRO-11 
program, the programmer uses the following two lines of code: 



.MCALL 
DRERR$ 



DRERRi? 



STANDARD ERROR CODES RETURNED BY DIRECTIVES IN THE DIRECTIVE STATUS 
WORD 

EVENT FLAG WAS CLEAR 
OPERATION COMPLETE, SUCCESS 
EVENT FLAG WAS SET 



INSUFFICIENT DYNAMIC STORAGE 

SPECIFIED TASK NOT INSTALLED 

INSUFFICIENT DYNAMIC STORAGE FOR SEND 

UNASSIGNED LUN 

DEVICE DRIVER NOT RESIDENT 

TASK NOT ACTIVE 

DIRECTIVE INCONSISTENT WITH TASK STATE 

TASK ALREADY FIXED/UNFIXED 

ISSUING TASK NOT CHECKPOINTABLE 

TASK IS CHECKPOINTABLE 

RECEIVE BUFFER TOO SMALL 

PRIVILEGE VIOLATION 

SPECIFIED VECTOR ALREADY IN USE 

NO SWAP SPACE AVAILABLE 

SPECIFIED VECTOR ILLEGAL 



DIRECTIVE ISSUED/NOT ISSUED FROM AST 

ISR OR ENABLE/DISABLE INTERRUPT ROUTINE 

NOT WITHIN 4K WORDS FROM VALUE OF 

BASE ADDRESS & 177700 

WINDOW HAS I/O IN PROGRESS 

ALIGNMENT ERROR 

ADDRESS WINDOW ALLOCATION OVERFLOW 

INVALID REGION ID 

INVALID ADDRESS WINDOW ID 

INVALID TI PARAMETER 

INVALID SEND BUFFER SIZE (>255.) 

LUN LOCKED IN USE 

INVALID UIC 



IS.CLR 


+ 00 


IS .sue 


+01 


IS. SET 

; 


+02 


1 

lE.UPN 


-01. 


IE. INS 


-02. 


lE.UNS 


-04. 


lE.ULN 


-05. 


lE.HWR 


-06. 


IE. ACT 


-07. 


IE. ITS 


-08. 


IE. FIX 


-09. 


lE.CKP 


-10. 


lE.TCH 


-11. 


lE.RBS 


-15. 


lE.PRI 


-16. 


lE.RSU 


-17. 


IE. NSW 


-18. 


lE.ILV 


-19. 


J 
; 

IE. AST 


-80. 


IE. MAP 


-81. 


lE.IOP 


-83. 


lE.ALG 


-84. 


lE.WOV 


-85. 


lE.NVR 


-86. 


lE.NVW 


-87. 


lE.ITP 


-88. 


IE. IBS 


-89. 


lE.LNL 


-90. 


lE.IUI 


-91. 
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STANDARD ERROR CODES 



lE.IDU -92. INVALID DEVICE OR UNIT 

lE.ITI -93. INVALID TIME PARAMETERS 

lE.PNS -94. PARTITION/REGION NOT IN SYSTEM 

lE.IPR -95. INVALID PRIORITY (>250.) 

lE.ILU -96. INVALID LUN 

lE.IEF -97. INVALID EVENT FLAG NUMBER 

lE.ADP -98. PART OF DPB OUT OF USER'S SPACE 

lE.SDP -99. Die OR DPB SIZE INVALID 



j^^^^^^ 



.SWP^^fi 
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APPENDIX C 
DIRECTIVE IDENTIFICATION CODES 



Directive Identification Codes (DICs) are used to identify each 
directive. The DIG appears in the low byte of the first (or only) 
word in the Directive Parameter Block (DPB) . The DPS length (in 
words) appears in the high byte of the first DPB word. Thus, both 
bytes make up the word format shown below: 



First Word 
In DPB 



DPB Length 


Die 



(High byte) 



(Low byte) 



The remainder of this appendix contains a listing of directives 
arranged in numerical sequence, according to the octal value for the 
first DPB word. In addition, the DIG and DPB lengths are included as 
decimal values as they appear in Chapter 6. 

This list can be used as a software debugging aid to quickly identify 
directives based on the octal value of the first word in a DPB. An 
example for the SDAT$ directive is provided below, illustrating the 
manner in which the octal value is obtained: 



First Word 
In DPB 



5(10) 



71(10) 



Octal Byte 
Values 



Binary Word 
Value 



5(8) 



101 



01 



107(8) 



000 111 



Octal Word 
Value 



2507 (=SDAT$) 
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DIRECTIVE IDENTIFICATION CODES 



Octal Value For 
DPB First Word 


Directive 
(Macro Call) 


Decimal Values For 


Die 


DPB Length 


433 


CMKT$ 


27. 


X • 


443 


DECL$ 


35. 


X • 


455 


SPND$S 


45. 


J. • 


461 


WSIG$S 


49. 


■L • 


463 


EXIT$S 


51. 


.L • 


537 


DCSP$ 


95. 


2. , 


541 


ENCP$S 


97. 


■L • 


543 


DSAR$S or IHAR$S 


99. 


■L • 


545 


ENAR$S 


101. 


1 ^ 


563 


ASTX$S 


115. 


X • 


575 


GSSW$S 


125. 


1. • 


603 


STOP$S 


131. 


-L • 


64 3 '-''^^:Hu 


:^«RMAE$':- ■-■:.;■.'!:.-■::.■-■': j..:V/::; 


163. 


■J- • 


1015 .;^C'.:: 


;■ ■■stAF$:::c^-- ■;:;■; 


13. 


2. 


1025 


SRRA$ 


21. 


2. 


1035 


EXST$ 


29. 


2. 


1037 


CLEF$ 


31. 


2. 


1041 


SETF$ 


33. 


2. 


1047 


RDAF$ 


39. 


2. 


1051 


WTSE$ 


41. 


2. 


1065 


EXIF$ 


53. 


2. 


1067 


CRRG$ 


55. 


2. 


1071 


ATRG$ 


57. 


2. 


1073 


DTRG$ 


59. 


2. 


1075 


GTIM$ 


61. 


2. 


1077 


GTSK$ 


63. 


2. 


1121 


RREF$ 


81. 


2. 


1153 


SRDA$ 


107. 


2. 


1155 


SPRA$ 


109. 


2. 


1157 


SFPA$ 


111. 


2. 


1161 


GMCX$ 


113. 


2. 


1165 


CRAW$ 


117. 


2. 


1171 


MAP$ 


121. 


2. 


1173 


UMAP$ 


123. 


2. 


1207 


STSE$ 


135. 


2. 


i22mmm--y.\ 


;- ;i,El:.VT$ :■:■-■; -^ ■■:■-. 


'y-^ir. 151. 


2. 


1235 


CRGF$ 


157. 


2. 


1237 


ELGF$ 


159. 


2. 


1241 


. :..-.S3'AF$ ■ . . 


;y 161. 


2. 


1245 


:- skek^::- :::-;'■■.:■::-:■■ :■:::- 


x-v;^; 165. 


2. 


1247 


■■■:.-5REA$' 


■yjMl 167. 


2. 


1405 


GLUN$ 


5. 


3. 


1431 


CSRQ$ 


25. 


3. 


1433 


CMKT$ 


27. 


3. 


1447 


RDXF$ 


39. 


3. 


1453 


WTLO$ 


43. 


3. 


1457 


RSUM$ 


47. 


3. 


1523 


ABRT$ 


83. 


3. 


1531 


EXTK$ 


89. 


3. 


1547 


SVDB$ 


103. 


3. 


1551 


SVTK$ 


105. 


3. 


1605 


USTP$ 


133. 


3. 


1611 


STLO$ 


137. 


3. 


1622 


CNCT$ 


146. 


3. 


■ ■■ 'Un-'i-' -'^^ri ' 


SCAL$S 


155. 


•■ 3'.- •. 


2007 


ALUN$ 


7. 


4. 


2011 


ALTP$ 


9. 


4. 


2101 


GPRT$ or GREG$ 


65. 


4. 


2113 


RCVD$ 


75. 


4. 


2115 


RCVX$ 


77. 


4. 
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DIRECTIVE IDENTIFICATION CODES 



Octal Value for 
DPB First Word 


Directive 
(Macro Call) 


Decimal Values For 


DIG 


DPB Length 


2 213 


RCST$ 


139. 


4. 


222.3 


■■;---^ -■:■;; --■bmst$;:v'v'-',':: -3 


'V;;^-v/;i47.^-;>-,- 


4. 


2 427 


MRKT$ 


23. 


5. 


2 50 5 


SREF$ 


69. 


5. 


2 50 7 


SDATS 


71. 


5. 


2625 


CRVT$ 


149. 


5. 


3113 


VRCD$ 


75. 


6. 


3115 


VRCX$ 


77. 


6. 


3213 


VRCS$ 


139. 


6. 


3413 


RQST$ 


11. 


7. 


3601 


CINT$ 


129. 


7. 


3615 


SDRC$ 


141. 


7. 


4107 


VSDA$ 


71. 


a. 


5421 


RUN$ 


17. 


11. 


6001 


QIO$ 


1. 


12. 


6003 


QIOW$ 


3. 


12. 


6413 


SPWN$ 


11. 


13. 


7013 


SPWN$ 


11. 


14. 


12377 


GMCR$ 


127. 


41. 
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APPENDIX D 
RSX-11 SYSGEN SELECTION OF EXECUTIVE DIRECTIVES 



The following list contains all Executive directive macro calls 
described in this manual and means of selection at SYSGEN time. Those 
directives not available for specific RSX-11 systems are noted as N/A. 
Directives that are SYSGEN options are noted as 0. The number in 
parentheses after the refers to the SYSGEN options at the end of the 
list. Directives that are standard (not SYSGEN options) are indicated 
by an asterisk (*) . 



Directive 

Macro 

Call 



ABRT$ 

ALTP$ 

ALUN$ 

ASTX$S 

ATRG$ 

CINT$ 

CLEF$ 

CMKT$ 

CNCT$ 

CRAW$ 

CRGF$ 

CRRG$ 

:!fRVT5 

CSRQ$ 

DECL$S 

DSAR$S 

DSCP$S 

DTRG$ . 

ELAW$ 

ELGF$ 

ELVT? 

EMST$ 

ENAR$S 

ENCP$S 

EXIF$ 

EXIT$S 

EXST$ 

EXTK$ 

GLUN$ 

GMCR$ 

GMCX$ 

GPRT$ 

GREG$ 

GSSW$S 

GTIM$ 



or IHAR$S 



System Type 



RSX-llS 



(1) 

(2) 
(3) 
(1) 



(4) 
(3) 
(5) 



N/A 
N/A 



(2) 
N/A 
(3) 
(3) 
(5) 
N/A 
N/A 
(2) 
N/A 



N/A 
(1) 

N/A 
(3) 
(1) 
(3) 
(1) 



RSX-llM 



(1) 
* 



(2) 
(3) 

(1) 






* 

(4) 
(3) 
(5) 
(3) 
N/A 



(2) 

(7) 

(3) 

(3) 

(5) 
N/A 
N/A 

(2) 

(7) 
* 
* 

(4) 

(1) 
* 

* 



RSX-llM-PLUS 



(3) 
(1) 
(3) 
(1) 



* 
* 

* 


* 

* 

* 




* 



* 
* 
* 
* 



* 

o 



* 
* 
* 


* 
* 
* 


* 




* 



(3) 



(4) 
(3) 

(3) 
(6) 



(3) 
(3) 

(6) 
(4) 



(4) 



(3) 

(3) 
(1) 
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Directive 

Macro 
Call 



GTSK$ 

MAP$ 

MRKT$ 

QIO$ 

QIOW$ 

RCST$ 

RCVD$ 

RCVX$ 

RDAF$ 

RDXF$ 

'RHAE$:Sil 

RQST$ 

RREF$ 

RSUM$ 

RUN$ 

SDAT$ 

^SDRG$-^:-' 

SETF$ 

SFPA$ 

SPND$S 

SPRA$ 

SPWN$ 

SRDA$ 

SREA$ 

SREF$ 

SRRA$ 

STAF$ : 

STLO$ 

STOP$S 

STSE$ 

SVDB$ 

SVTK$ 

UMAP$ 

USTP$ 

;VRGD$. 

WSIG$S 

WTLO$ 

WTSE$ 



System Type 



RSX-llS 



O (1) 
(3) 
* 



N/A 
(8) 

O (8) 
* 

(5) 

* 

(8) 
* 

* 

(8) 

N/A 

* 

(2, 11) 

N/A 
* ■ ■ 

(2, 12) 

(4) 

(2, 8) 

N/A 

(8) 

(2, 3, 8) 

N/A 

(4) 

(4) 

(4) 



(3) 
(4) 

N/A;"- 

* 

* 
* 



RSX-llM 






(1) 





(3) 


* 




* 




* 







(4) 





(8) 





(8) 


* 







(5) 


mm Ac ms 


* 







(8) 


* 




* 




N/A 





(8) 


N/A 


* 







(2, 11) 


N/A 



SYSGEN Options 

1. Specific Executive directive support 

2. AST support 

3. Memory management directives 

4. Parent/offspring tasking support 

5. Group-global event flag support 
5. Virtual termiptaiiiSjuppbrt^ 

7. Checkpointing support 



RSX-llM-PLUS 



* 




* 




(2, 


12) 


* 




(4) 







(4) 


(2, 


8) 


* 




N/A 




* 




(8) 







(3) 


(2, 


3, 8) 


* 




N/A 




•■•■ 


($):■ 


(4) 




* 




(4) 




* 




(4) 




* 




* 




* 




* 




* 




(3) 







(3) 


(4) 




* 




N/A 







(13) 


N/A 







(13) 


N/A 







(13) 


N/A 







(13) 


* 




* 




* 




* 




* 




* 






* 

* 

* 

* 

* 

* 

:o 



* 


* 


* 


* 



(3) 



(9) 
(3) 

(10) 

(4) 

(11) 



..^B^Wlk 
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8. Send/receive by reference directives 

9. Miil Liprocessor support 

10. Supervisor mode library support 

11. Floating point processor support 

12. Powerfail recovery support 

13. Secondary pool support 
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INDEX 



Abort AST, 6-137 
Abort Task, 6-7 
Aborting a task, 6-7, 6-37 
Activating a task, 4-1, 6-105, 
6-112, 6-121, 6-131, 6-155 
Active task, 1-15 
Address, 
DPB, 1-2 

error routine, 1-7 
Address mapping, 3-1, 3-6, 3-7 
Address space, 

logical, 3-2, 3-4 
virtual, 3-2 
User-mode, 5-3, 5-4 
Supervisor-mode, 5-3, 5-4, 6-117 
Address window, 
creating, 6-31 
eliminating, 6-51 
mapping, 6-83 
unmapping, 6-153 
virtual, 3-2, 3-3, 6-31 
Affinity, task 

CPU/UNIBUS, 5-4, 6-143 
removing, 6-104 
Alignment boundaries, 

offset, 6-31, 6-32 
Alter priority, 6-9 
Arguments, 

integer, 1-11 
INTEGER* 2, 1-11 
optional, 6-5 
optional subroutine, 1-10 
Array, 

integer, 1-11 
RDB integer, 3-14 
WDB integer, 3-17 
Assign LUN, 6-11 
AST, 2-1, 2-4, 2-6 
abort, 6-137 

floating point processor, 6-124 
power recovery, 6-129 
receive data, 6-135 
receive-by-reference, 6-141 
parity error, 6-126 
receive data, 6-135 
requested exit (abort) , 6-137 
AST recognition, 
disabling, 6-46 
enabling, 6-57 
AST service exit, 6-13, 6-14 
AST service routine, 2-7 
abort, 6-137 
cancel mark time, 6-27, 6-28, 

6-86, 6-87 
floating point processor 
exception, 6-124, 6-125 



AST service routine (Cont.) 

I/O completion, 6-90, 6-92, 6-93 
interrupt processing, 6-17 to 

6-22 
mark time, 6-26, 6-27, 6-86, 

6-87 
MCR command line, 6-69 
offspring task exit, 6-29, 

6-121, 6-131 
parity error, 6-126 
power recovery, 6-129, 6-130 
receive-by-reference, 6-141, 

6-142 
receive data, 6-135, 6-136 
requested exit, 6-137 
virtual terminal, 6-39 to 6-42 
service routine exit, 6-13, 
6-14 
Asynchronous System Trap 
(AST) , 2-1, 2-4, 2-6 
Attach Region, 6-15 
Attaching to region, 3-8, 6-15, 

6-36 
Attachment descriptor, 3-8 

B 

Bit definitions, 3-10, 3-13 
Block, 

Directive Parameter (DPB) , 

1-2, 1-4, 1-6 
Group global Event 

Flag (GFB) , 6-35, 6-53 
Region Definition (RDB) , 3-10 

to 3-14 
Window Definition (WDB), 3-10, 
3-14 to 3-17 
Blocked task, 1-16 
Blocking a task, 6-166, 6-168 
Blocks, window, 3-2 
Boundaries, 

offset alignment, 6-31, 6-83 
Byte, DPB size, 1-2, C-1 



$C form, 1-6 
CALL ABORT, 6-7 
CALL ALTPRI, 6-9 
CALL ASNLUN, 6-15 
CALL CANALL, 6-44 
CALL CANMT, 6-27 
CALL CLREF, 6-26 
CALL CNCT, 6-2 9 
CALL CRAW, 6-31 
CALL CRGF, 6-35 
CALL CRRG, 6-36 
CALL CRVT, 6-39 
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CALL DSASTR, 6-46 
CALL DECLAR, 6-45 
CALL DISCKP, 6-48 
CALL DTRG, 6-49 
CALL ELAW, 6-51 
CALL ELGF, 6-53 
CALL ELVT, 6-54 
CALL EMST, 6-56 
CALL ENASTR, 6-57 
CALL ENACKP, 6-58 
CALL EXITIF, 6-59 
CALL EXIT, 6-61 
CALL EXST, 6-63 
CALL EXTTSK, 6-64 
CALL GETLUN, 6-66 
CALL GETMCR, 6-69 
CALL GETPAR, 6-74 
CALL GETREG, 6-76 
CALL GETTSK, 6-81 
CALL GMCX, 6-71 
CALL INASTR, 6-46 
CALL MAP, 6-83 
CALL MARK, 6-86 
CALL PWRUP, 6-129 
CALL QIO, 6-90 
CALL RCST, 6-95 
CALL REDEF, 6-102 
CALL READSW, 6-78 
CALL RECEIV, 6-97 
CALL RECOEX, 6-99 
CALL REQUES, 6-105 
CALL RESUME, 6-111 
CALL RMAF, 6-104 
CALL RREF, 6-108 
CALL RUN, 6-112 
CALL SEND, 6-119 
CALL SETEF, 6-123 
CALL SDRC, 6-121 
CALL SPAWN, 6-131 
CALL SREF, 6-138 
CALL STAF, 6-143 
CALL STLOR, 6-145 
CALL STOP, 6-147 
CALL STOPFR, 6-148 
CALL SUSPND, 6-128 
CALL UNMAP, 6-153 
CALL USTP, 6-155 
CALL VRCD, 6-156 
CALL VRCS, 6-158 
CALL VRCX, 6-160 
CALL VSDA, 6-162 
CALL WAITFR, 6-168 
CALL WFLOR, 6-166 
CALL WFSNE, 6-164 
CALL WTQIO, 6-93 
Calls, 

macro, 1-5 

subroutine, 1-12 
Cancel Mark Time Requests, 6-27 



Cancel Time Based Initiation 

Requests, 6-44 
Checkpointing, 6-19 

disabling, 6-48 

enabling, 6-58 
Clear Event Flag, 6-26 
Code, 

Directive Identification, 
(Die) , 1-2, C-1 

User Identification (UIC) , 
6-81, 6-106 
CcJdes, 

error, 1-3 

standard error, B-1 
Command line, getting 

MCR, 6-69 
Common event flags, 2-2 
Common regions, 

static, 3-4 
Conditional task 
termination. 
Conditions, 

FORTRAN error, 1-14 
Connect, 4-1, 4-2, 6-29 
Connect, Send, Request And, 

6-121 
Connect to Interrupt Vector, 6-17 
Console switch registers, 6-78 
Conventions, 

directive, 6-5 

macro name, 1-5 
CPU affinity, 5-4 

setting, 6-143 

removing, 6-104 
Create Address Window, 6-31 
Create Group Global Event Flags, 

6-35 
Create Region, 6-36 
Create Virtual Terminal, 6-39 



Data, 

receiving, 6-95, 6-97, 6-99 
receiving variable length 

data, 6-156, 6-158, 6-160 
sending, 6-119 

sending variable length data, 
6-162 
Data AST, receive, 6-135 
Data structures, user, 3-10 
Debugging aid SSTs, 6-149, 6-151 
Declare Significant Event, 6-45 
Declaring significant event, 6-45, 

6-86, 6-119, 6-162 
Default UIC, 6-114 
Definition Block, 

Region (RDB) , 3-10 to 3-14 
Window (WDB) , 3-10, 3-14 to 3-17 
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INDEX 



Delta time, 

schedule, 6-112 
Detach Region, 6-49 
Die, 1-2, C-1 
DIR$ macro, 1-6, 1-7 
Directive categories, 6-1 
Directive conventions, 6-5 
Directive definition, 

system, 1-1 
Directive functions, 

system, 1-1 
Directive Identification Code 

(DIG) , 1-2, C-1 
Directive macros, using, 1-3, 1-4 
Directive Parameter Block (DPB) , 

1-2, 1-4, 1-6 
Directive processing, 

system, 1-2 
Directive restrictions. 
Directive selection during 
SYSGEN, D-1 

nonprivileged task, 1-18 
Directive Status Word (DSW) , 1-2 
Directive summary, system, 6-2, 

6-3, 6-4, A-1 
Directives, 

implementing system, 1-1 

memory management, 3-1 
Disable AST Recognition, 6-46 
Disable Checkpointing, 6-48 
Dispatching, Executive-level, 

5-5, 5-6 
Dormant task, 1-16 
DPB, 1-2, 1-4, 1-6 
DPB, 

creating a, 1-4 

predefined, 1-7 
DPB address, 1-2, 1-4 
DPB pointer, 1-2, 1-4 
DPB size byte, 1-2, C-1 
DSW, 1-2 
DSW values, 1-3 
Dynamic regions, 3-4 



EFN, 2-2 

Eliminate Address Window, 6-51 

Eliminate Group Global Event 

Flags, 6-53 
Eliminate Virtual Terminal, 6-54 
Emit Status 
EMT, 1-1, 1-2, 1-4 
Emulator trap (EMT) , 1-1 
Enable AST Recognition, 6-57 
Enable Checkpointing, 6-58 
Entry points, routine, 2-4 
Error codes, standard, 1-3, B-1 
Error conditions, FORTRAN, 1-15 



Error routine address, 1-7 
Error status, 1-3 
Event , 

declaring significant, 6-45, 
6-86, 6-119, 6-162 

significant, 2-1, 6-45 

waiting for, 6-166, 6-168 

stopping for, 6-145, 6-166 
Event flag numbers (EFNs) , 2-2, 

6-5 
Event flags, 2-1 

common, 2-2 

group global, 2-2, 6-34, 6-53, 
6-103 

local, 2-2 

logical OR of, 6-145, 6-166 

reading, 6-102, 6-103 

setting, 6-123 

testing, 2-3 

using, 2-2 
EX$ERR, 4-2 
EX$SEV, 4-2 
EX$SUC, 4-2 
EX$WAR, 4-3 
Examples, 

connecting and passing status, 
4-4 

event flag usage, 2-3 

macro call, 1-8 
Exit, 6-61 

If, 6-59 

task, 1-3, 6-59, 6-61 

task, with status, 4-1 to 4-4, 
6-63 
Expansions, macro, 1-9 
Extend Task, 6-64 
EXTERNAL, 6-129 



Flag, 

clearing event, 6-26 

Create Group Global Event, 
6-35 

Eliminate Group Global Event, 
6-53 

setting event, 6-123 

stopping for event, 6-145, 6-166 

waiting for event, 6-166, 6-168 
Flag numbers (EFNs) , 

event, 2-2, 6-5 
Flag polarity, 

reporting, 6-102, 6-103, 6-123 
Flags, 

common event, 2-2 

event, 2-1 

group global, 2-2, 6-35, 6-53, 
6-103 

local event, 2-2 
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Flags (Cont.) 

logical OR of event, 6-145, 
6-166 

reading event, 6-102, 6-103 

testing event, 2-3 

using event, 2-2 
Floating-Point Processor 
Exception AST, 6-124 
Fork level, 6-17 
Form, 

$, 1-6 

$C, 1-6 

$S, 1-6 
Format , 

stack, 2-5, 2-7, 2-8 
FORTRAN , 

error conditions, 1-4 

subroutines, 1-9 
summary, 1-12 
using, 1-10 
Functions, 

system directive, 1-1 



General Information Directive, 

1-18 
Get LUN Information, 6-66 
Get Mapping Context, 6-71 
Get MCR Command Line, 6-69 
Get Partition Parameters, 6-7 4 
Get Region Parameters, 6-7 6 
Get Sense Switches, 6-78 
Get Task Parameters, 6-81 
Get Time Parameters, 6-79 
Getting current time, 6-79 
Getting issuing task parameters, 

6-81 
Getting LUN information, 6-66 
Getting mapping context, 6-71 
Getting MCR command, 6-69 
Getting partition parameters, 6-74 
Getting region parameters, 6-7 6 
Getting switch register contents, 

6-78 
$$GLB, 1-8 
Group global event flag, 2-2, 

6-35, 6-53, 6-103 
Group Global Event Flag Control 

Block, 6-35, 6-53 
GFB, 6-35, 6-53 
GS.DEL, 6-35, 6-53 

I 

I/O request, 

queuing, 6-90, 6-93 
Identification, 

region, 3-5 

User Code (UIC) , 6-81, 6-106 

window, 3-2 



Identification Code, 

Directive (DIG) , 1-2 

User (UIC), 6-81, 6-106 
Inhibit AST Recognition, 6-46 
Installed task, 

removing, 1-18 
Integer arguments, 1-11 
Integer array, 1-11 

RDB, 3-14 

WDB, 3-17 
INTEGER*2 arguments, 1-11 
Interrupt Service Routine, 

6-17, 6-20 
Interrupt Transfer Block, 6-17, 

6-20, 6-22 
Interrupts, 

software, 2-3 
Interval, 

reschedule, 6-112 

time, 6-86 to 6-88 
Intervals, time, 6-88 
ISA standard call, 6-86, 6-112, 

6-115 
ISA subroutines, 1-9 
ISR, 6-17, 6-20 
ITB, 6-17, 6-20, 6-22 

K 

KTll memory management unit, 3-1 



Library, 

object module, 1-10 

supervisor mode, 3-1, 3-2, 3-3, 

5-3, 5-4, 6-117 
system macro, 1-5 
Local event flags, 2-2 
Logical address space, 3-2, 3-4 
Logical OR of event flags, 6-145, 

b-lbb 
Logical Unit Numbers (LUNs) , 

6-5, 6-11 
LUN information, getting, 6-66 
LUNs, 6-5 

assigning, 6-11 



M 

Macro call examples, 1-8 
Macro calls, 1-5 
Macro expansions, 1-8 
Macro library, 

system, 1-5 
Macro name conventions. 
Macros, 



using directive, 1-4, 

gnitude values, 6-86, 

Map Address Window, 6-83 



1-5 
1-5 



Magn 
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Mapping, 

address, 3-1, 3-6, 3-7 

privileged task, 3-18 
Mapping context, 

getting, 6-71 
Mark Time, 6-86 
Mark time request, 

cancelling, 6-27 
Mask word, 

Wait for, 2-7 
.MCALL directive, 1-5 
MCR command, 

getting, 6-69 
Memory management 

directives, 3-1 
Memory-management unit, 

KTll, 3-1 
Module library, 

object, 1-10 
Multiuser task Executive-level 
dispatching, 5-5 



N 



Name conventions, 
macro, 1-5 

Names, task, 1-10 

Numbers, 

Event Flag (EFNs) , 2-2, 6-5 
Logical Unit (LUNs) , 6-5, 6-11 



Object module library, 1-10 
Offset alignment boundaries, 6-31, 

6-83 
Offsets, symbolic, 1-8 
Offspring, 

emitting status, 4-2, 6-56, 

6-63 
exit, 4-2 

exit with status, 4-2, 6-63 
starting, task, 4-1, 4-2 
spawn, 6-131 
status, task, 4-1 
task defined, 4-1 
tasking support, 4-1 
use of virtual terminals, 4-1, 
4-2, 5-2 
Optional arguments, 6-5 
Optional subroutine arguments, 
1-10 



Packet, send-by-reference, 6-138 

Parameters, 

getting issuing task, 6-81 
getting partition, 6-74 



Parameters (Cont.) 

getting region, 6-76 

RDB, 3-18 

time, 6-79, 6-112 

WDB, 3-18 
Parent/offspring tasking, 4-1 

directive summary, 4-1, 4-2 
Parent task, 4-2 

receiving status, 4-1, 4-2 
Parity error AST, 6-12 6 
Partition parameters, 

getting, 6-74 
Pointer, DPB, 1-2, 1-4 
Power recovery AST, 6-12 9 
Power recovery subroutine, 6-129 
Predefined DPB, 1-7 
Priority, 

altering task, 6-9 
Privileged task mapping, 3-18 
Processing, 

system directive, 1-2 
Processor AST, 

floating point, 6-124 
Processor Status word (PS) , 1-2 
Protection, region, 3-8 
Protection UIC, 6-106, 6-114 
PS, 1-2 

Q 

QIO directive, 6-90 
Queue , 

receive, 6-119 

receive-by-reference, 6-108, 
6-138 
Queue I/O Request, 6-90 
Queue I/O Request And Wait, 6-93 

R 

R.GID, 3-12, 6-15, 6-37, 6-49 
R.GNAM, 3-12, 6-15, 6-37 
R.GPAR, 3-12, 6-37 
R.GPRO, 3-12, 6-37 
R.GSIZ, 3-12, 6-16, 6-36 
R.GSTS, 3-12, 6-15, 6-37, 6-49 
RDB, 3-10 

generating an, 3-11, 3-12 
RDB integer array, 3-14 
RDB parameters, 3-18 
Read All Event Flags, 6-102 
Read Extended Event Flags, 6-102 
Receive By Reference, 6-108 
Receive Data, 6-97 
Receive data AST, 6-135 
Receive Data Or Exit, 6-99 
Receive Data Or Stop, 6-95 
Receive queue, 6-119 
Receive-by-reference AST, 6-141 
Receive-by-reference queue, 6-108 
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Receiving data, 6-95, 6-97, 6-99 
Region, 

attaching to, 3-5, 6-15, 6-16 
creating, 6-36 
detaching from, 6-49 
sending reference to, 6-138 
Region Definition Block (RDB) , 

3-10 
Region identification, 3-5 
Region parameters, 

getting, 6-76 
Region protection, 3-8 
Region reference, 6-138 
Region status word (R.GSTS) , 3-10, 

6-15, 6-37, 6-49 
Regions, 

dynamic, 3-4 
sharable, 3-4 
shared, 3-5 
static common, 3-4 
task, 3-4 
Registers, 

console switch, 6-78 
task, 1-2, 2-6 
Remove Affinity, 6-104 
Removing installed task, 1-18 
Request Task, 6-105 
Requesting a task, 6-105, 6-112, 

6-121 
Requests, 

cancelling Mark Time, 6-27 
cancelling time-based, 6-44 
Reschedule interval, 6-112 
Restrictions, nonprivileged 

task directive, 1-18 
Resuming suspended task, 6-111 
Routine , 

AST service, 2-7 

SST service, 2-4, 6-149, 6-151 

Supervisor-mode completion, 5-3, 

5-4, 6-117 
terminating AST service, 6-13 
Routine address, 
error, 1-7 
Supervisor-mode 

completion, 5-3, 5-4, 6-117 
Routine entry points, 2-4 
RS.ATT, 3-11, 6-36 
RS.CRR, 3-11, 6-37 
RS.DEL, 3-11, 6-16, 6-37 
RS.EXT, 3-11, 6-16, 6-37 
RS.MDL, 3-11, 6-37, 6-49 
RS.NDL, 3-11, 6-36 
RS.NEX, 3-11, 6-37 
RS.RED, 3-11, 6-16, 6-37 
RS.UNM, 3-11, 6-37, 6-49 
RS.WRT, 3-11, 6-16, 6-37 
RSX-llM-PLUS, 1-19, 5-1 
Run Task, 6-112 
Running a task, 6-105, 6-112 



$S form, 1-6 

Schedule delta time, 6-112 

Scheduling a task, 6-112 

Send By Reference, 6-138 

Send Data, 6-119 

Send-by-reference packet, 6-138 

Send, Request And Connect, 4-2, 

6-121 
Sending data, 6-119 
Sending variable length data, 

6-162 
Sending reference to 

region, 6-138 
Service routine 

(see routine) 
Set Affinity, 6-143 
Set Event Flag, 6-123 
Shared regions, 3-5 
Significant event, 2-1, 6-164 

declaring, 6-45, 6-119, 6-162 
Size, extending task, 6-64 
Software interrupts, 2-3 
Spawn, 4-1, 4-2, 6-131 
Spawning tasks, 4-1, 4-2 
Specify Floating Point 

Processor, 6-124 
Specify Parity Error AST, 6-126 
Specify Power Recovery AST, 6-129 
Specify Receive Data AST, 6-135 
Specify Receive-By- 

Reference AST, 6-141 
Specify Requested Exit AST, 6-137 
Specify SST Vector Table 

For Debugging Aid, 6-149 
Specify SST Vector Table For' Task, 

6-151 
SST, 2-4 
SST service routines, 2-4, 6-149, 

6-151 
SST vector table, 6-149, 6-151 
SSTs, 2-4 

debugging aid, 6-149 

task, 6-151 
Stack format, 2-5, 2-8 
Standard error codes, B-1 
State, task, 1-16 
Static common regions, 3-4 
Status, error, 1-3 
Status, offspring task, 4-1 

return to parent task, 4-1 to 
4-4 
Status Word, 

Directive (DSW) , 1-2 

Program (PS) , 1-2 

region (R.GSTS) , 3-11 

window (W.NSTS) , 3-14 
STOP, 6-61 
Stop, 6-147 



,^^^ 



Index- 6 



INDEX 



Stop For Logical OR Of Event 

Flags, 6-145 
Stop For Single Event Flag, 

6-148 
Stop, Receive Data Or, 6-95 
STOP statement message, 6-62 
Stopped task state, 1-16 
Structures, user data, 3-10 
Subroutine arguments, 

optional, 1-10 
Subroutine calls, 1-11 
Subroutines, 

FORTRAN, 1-9 

ISA, 1-9 

summary FORTRAN, 1-12 

using FORTRAN, 1-10 
Summary , 

system directive, 6-2, A-1 
Summary FORTRAN subroutines, 1-12 
Supervisor Call, 6-117 
Supervisor-mode addressing, 3-1, 

3-2 
Supervisor-mode completion 

routine, 5-3, 5-4, 6-117 
Supervisor-mode library routines, 

5-3 
Suspend, 6-128 

Suspended task, resuming, 6-111 
Suspending a task, 6-128, 6-164 
Switch register, 

getting contents of, 6-78 
Symbolic offsets, 1-8 
Synchronization , 

stop-bit, 2-11 
Synchronous System Trap (SST) , 

2-4 
SYSGEN, directive selection 

during, D-1 
System directive definition, 1-1 
System directive functions, 1-1 
System directive processing, 1-2 
System directive summary, 6-2, A-1 
System directives, implementing, 

1-1 
System macro library, 1-5 
System Trap, 2-3 

Asynchronous (AST), 2-1, 2-4, 
2-6 

Synchronous (SST) , 2-4 



TABLE , 

SST vector, 6-149, 6-151 

trap vector, 2-4 
Task, 

aborting a, 6-7, 6-137 

activating a, 6-105, 6-112, 
6-121, 6-131, 6-155 

active, 1-16 



Task (Cont.) 

affinity, 6-104, 6-143 

altering priority, 6-9 

blocked, 1-16 

blocking a, 6-166, 6-168 

communication , 

directives for, 4-2 

connecting to, 4-1 to 4-4 

dispatching multiuser, 5-5 

dormant, 1-16 

ready-to-run, 1-16 

removing installed, 1-18 

requesting a, 6-105, 6-112, 
6-121 

resuming suspended, 6-111 

rundown count, 6-29, 6-39, 
6-54, 6-131 

running a, 6-105, 6-112 

scheduling a, 6-112 

spawning a, 4-1, 6-131 

states of, 1-16 

passing status of, 4-3 

stopping a, 2-11, 4-4, 6-145, 
6-147, 6-148 

suspending a, 6-128, 6-164 

synchronization, 2-11 

unstopping a, 2-11, 4-4, 6-155 
Task CPU/UNIBUS affinity, 5-4 
Task execution, 

terminating, 6-7, 6-59, 6-61, 
6-137 
Task Exit, 6-61 

conditional, 6-59 
Task exits, 1-3 
Task mapping, 

privileged, 3-18 
Task names, 1-10 
Task parameters, 

getting issuing, 6-81 
Task priority, 

altering, 6-9 
Task regions, 3-4 
Task registers, 1-2, 2-6 
Task size, extending, 6-64 
Task SSTs, 6-151 
Task state, 1-16 
Task termination, 

conditional, 6-59 
Terminal UIC, 6-81, 6-105 
Terminating task execution, 6-7, 

6-59, 6-61, 6-137 
Termination , 

conditional task, 6-59 
Terminator word, 6-71 
Testing event flags, 2-3 
Time, 

getting current, 6-79 

Schedule delta, 6-112 
Time interval, 6-86 to 6-88 
Time intervals, 6-88, 6-112 
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Time parameters, 6-7 9, 6-86 to 

6-88 
Time-based requests, 

cancelling, 6-44 
Trap, 

Asynchronous System (AST) , 
2-1, 2-4, 2-6 

Emulator (EMT) , 1-1 

Synchronous (SST) , 2-4 

system, 2-3 
Trap vector table, 2-5 



u 



UIC, 

default, 6-105, 6-114 

protection, 6-106, 6-114 

terminal, 6-81, 6-105 
UNIBUS run, 5-4 

specifying, 6-143 
Unmap Address Window, 6-153 
Unstop, 6-155 

Unstopping tasks, 2-11, 4-4 
User data structures, 3-10 
User Identification Code (UIC) , 
6-74, 6-105 



Values, 

DSVJ, 1-3 

magnitude, 6-112 
Variable Receive Data, 6-156 
Variable Receive Data Or Exit, 

6-160 
Variable Receive Data Or Stop, 

6-158 
Variable Send Data, 6-162 
Vector table, 

SST, 6-149, 6-151 

trap, 2-4 
Virtual address space, 3-2 
Virtual addresp window, 3-2 
Virtual terminal, 5-2 

creating, 6-39 

eliminating, 6-54, 6-60, 6-62, 
6-100, 6-131 

using, 5-2 

w 

W.NAPR, 3-15, 6-32, 6-71 
W.NBAS, 3-15, 6-33, 6-71 
W.NID, 3-15, 6-33, 6-51, 6-71, 
6-84, 6-109 



6-84, 



6-139 



W.NLEN, 3-15, 6-31, 6-71, 6-83, 

6-109, 6-138, 6-153 
W.NOFF, 3-15, 6-31, 6-71, 6-83, 

6-109, 6-138, 6-153 
W.NRID, 3-15, 6-32, 6-71, 

6-109, 6-138 
W.NSIZ, 3-15, 6-32, 6-71 
W.NSRB, 3-15, 6-71, 6-109, 
W.NSTS, 3-14 to 3-16, 6-31, 6-51, 

6-71, 6-83, 6-108, 6-138, 6-153 
Wait For Logical "OR" Of 

Event Flags, 6-166 
Wait For Significant Event, 6-164 
Wait For Single Event, 6-168 
Wait For mask word, 2-7 
WDB, 3-8, 3-16 

generating a, 3-16, 3-17 
WDB integer array, 3-17 
WDB parameters, 3-18 
Window , 

creating address, 6-31 
eliminating address, 6-51 
mapping address, 6-83 
unraapping address, 6-153 
virtual address, 3-2, 3-3, 6-31 
Window blocks, 3-2 
Window Definition Block (WDB) , 

3-10, 3-14 to 3-17 
Window identification, 3-2 
Window status word, (W.NSTS) , 3-14 
Word , 

Directive Status (DSW) , 1-2 
Processor Status (PS), 1-2 
region status (R.GSTS) , 3-10 
Wait For mask, 2-7 
window status (W.NSTS), 3-14, 
6-32, 6-51, 6-71, 6-83, 6-108, 
6-138, 6-153 
WS.64B, 3-15, 6-31 to 6-33, 6-83 
WS.BPS, 3-15, 6-33 
WS.CRW, 3-14, 6-33 
WS.DEL, 3-15, 6-33, 
WS.ELW, 3-14, 
WS.EXT, 
WS . MAP , 
WS.NAT, 
WS.NBP, 
WS . RES , 
WS.RCX, 3-15, 
WS.RED, 3-15, 
WS.RRF, 3-14, 6-109 
3-15, 6-33 
3-14, 



6-109 
6-33, 6-51 
3-15, 6-33, 6-109 
3-15, 6-32, 6-71, 6-108 



3-15, 6-33, 
3-14, 6-33 
3-15, 6-33 



6-138 



WS.SIS, 
WS.UNM, 

6-153 
WS.WRT, 3-15, 



6-33, 6-108 
6-34, 6-109 



6-33, 6-51, 6-84, 



6-32, 6-34, 6-71, 



6-84, 6-109 
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